Matrak API Reference

Hello, it's nice to meet you! Welcome to the Matrak API Reference.

The Matrak API integrates into your internal tech solutions, giving everyone across your supply chain a trusted single source of truth.

You'll gain insight into your materials tracking and control over your raw data, which can then be used for analyses and reporting to your team. By creating supply chain visibility, you can mitigate potential risks to construction projects, as well as enable better communication between your team members.

This API was built to allow you to edit, track and link materials in bulk. You can also create, update, delete and fetch material records. Or even link and associate materials to other containers and stillages.

That's just a few of the many things you can do with the Matrak API. This reference was written to guide you on its many capabilities, what you can do and how you can easily execute these features into your own tech solutions.

Contact

Matrak Support

support@matrak.com

Terms of Service

https://matrak.com/free-user-and-invited-user-terms/

API Endpoints
https://graphql.matrak.com.au/
REST API Endpoints
https://rest.matrak.com.au/
Headers
Authorization: <YOUR_TOKEN_HERE>
Version

1.0.0

Getting Started

Authentication

To access our APIs, you need an authentication key (API key). To obtain your API key, please contact our technical support team at support@matrak.com. Once you have your API key, include it in your requests to authenticate and interact with our services.

Using the API Explorer

You can explore and test our API using the Matrak GraphQL Explorer, available at https://graphql.matrak.com.au/. This web-based tool allows you to run queries and mutations against our live production data. Please use caution when making changes, as they will directly impact the live environment.

Sandbox Environment

Overview

Our Sandbox environment provides a safe and fully functional replica of our production environment, allowing developers to test their API integrations without affecting live production data. This environment is synced with production data daily, ensuring it remains up-to-date.

Access

The Sandbox environment can be accessed at https://sandbox.matrak.com.au/.

Using the GraphQL Editor

Developers can test their API usage in the GraphQL editor available at https://graphql.sandbox.matrak.com.au/.

Changelog

Future changes in this document will reflect changes in our API's

Queries

Project

Description

Get a specific Project

Response

Returns a Project

Arguments
Name Description
id - Int!

Example

Query
query Project($id: Int!) {
  Project(id: $id) {
    id
    name
  }
}
Variables
{"id": 123}
Response
{
  "data": {
    "Project": {"id": 987, "name": "abc123"}
  }
}
Queries

Record

Description

Get a specific Record

Response

Returns a Record

Arguments
Name Description
id - Int

Example

Query
query Record($id: Int) {
  Record(id: $id) {
    id
    record_id
    project {
      ...ProjectFragment
    }
    record_type {
      ...RecordTypeFragment
    }
    values {
      ...RecordValueFragment
    }
    value {
      ...RecordValueFragment
    }
    attachments {
      ...AttachmentFragment
    }
    childLink {
      ...LinkFragment
    }
    parentLink {
      ...LinkFragment
    }
  }
}
Variables
{"id": 987}
Response
{
  "data": {
    "Record": {
      "id": 987,
      "record_id": "abc123",
      "project": Project,
      "record_type": RecordType,
      "values": [RecordValue],
      "value": RecordValue,
      "attachments": [Attachment],
      "childLink": [Link],
      "parentLink": [Link]
    }
  }
}
Queries

RecordType

Description

Get a specific Record Type

Response

Returns a RecordType

Arguments
Name Description
id - Int

Example

Query
query RecordType($id: Int) {
  RecordType(id: $id) {
    id
    name
    category
    sub_category
    order
    descriptions {
      ...DescriptionFragment
    }
  }
}
Variables
{"id": 987}
Response
{
  "data": {
    "RecordType": {
      "id": 123,
      "name": "xyz789",
      "category": "abc123",
      "sub_category": "xyz789",
      "order": 987,
      "descriptions": [Description]
    }
  }
}
Queries

Trade

Response

Returns a Trade

Arguments
Name Description
id - Int!

Example

Query
query Trade($id: Int!) {
  Trade(id: $id) {
    id
    name
    created_at
    updated_at
  }
}
Variables
{"id": 123}
Response
{
  "data": {
    "Trade": {
      "id": 123,
      "name": "abc123",
      "created_at": "xyz789",
      "updated_at": "abc123"
    }
  }
}
Queries

_allRecordTypesMeta

Description

Get metadata about how many Record Types would be available after a filter is applied

Response

Returns a ListMetadata!

Arguments
Name Description
page - Int
perPage - Int
sortField - String
sortOrder - String
filter - RecordTypeFilter

Example

Query
query _allRecordTypesMeta(
  $page: Int,
  $perPage: Int,
  $sortField: String,
  $sortOrder: String,
  $filter: RecordTypeFilter
) {
  _allRecordTypesMeta(
    page: $page,
    perPage: $perPage,
    sortField: $sortField,
    sortOrder: $sortOrder,
    filter: $filter
  ) {
    count
  }
}
Variables
{
  "page": 987,
  "perPage": 987,
  "sortField": "xyz789",
  "sortOrder": "abc123",
  "filter": RecordTypeFilter
}
Response
{"data": {"_allRecordTypesMeta": {"count": 987}}}
Queries

_allRecordsMeta

Description

Get metadata about how many records would be available after a filter is applied

Response

Returns a ListMetadata!

Arguments
Name Description
page - Int
perPage - Int
sortField - String
sortOrder - String
filter - RecordFilter

Example

Query
query _allRecordsMeta(
  $page: Int,
  $perPage: Int,
  $sortField: String,
  $sortOrder: String,
  $filter: RecordFilter
) {
  _allRecordsMeta(
    page: $page,
    perPage: $perPage,
    sortField: $sortField,
    sortOrder: $sortOrder,
    filter: $filter
  ) {
    count
  }
}
Variables
{
  "page": 123,
  "perPage": 987,
  "sortField": "xyz789",
  "sortOrder": "xyz789",
  "filter": RecordFilter
}
Response
{"data": {"_allRecordsMeta": {"count": 123}}}
Queries

_allTradeMeta

Response

Returns a ListMetadata

Arguments
Name Description
page - Int
perPage - Int
sortField - String
sortOrder - String
filter - TradeFilter

Example

Query
query _allTradeMeta(
  $page: Int,
  $perPage: Int,
  $sortField: String,
  $sortOrder: String,
  $filter: TradeFilter
) {
  _allTradeMeta(
    page: $page,
    perPage: $perPage,
    sortField: $sortField,
    sortOrder: $sortOrder,
    filter: $filter
  ) {
    count
  }
}
Variables
{
  "page": 987,
  "perPage": 987,
  "sortField": "xyz789",
  "sortOrder": "xyz789",
  "filter": TradeFilter
}
Response
{"data": {"_allTradeMeta": {"count": 987}}}
Queries

allProjects

Description

Get all projects for your company

Response

Returns [Project!]!

Arguments
Name Description
page - Int
perPage - Int
sortField - String
sortOrder - String
filter - ProjectFilter

Example

Query
query allProjects(
  $page: Int,
  $perPage: Int,
  $sortField: String,
  $sortOrder: String,
  $filter: ProjectFilter
) {
  allProjects(
    page: $page,
    perPage: $perPage,
    sortField: $sortField,
    sortOrder: $sortOrder,
    filter: $filter
  ) {
    id
    name
  }
}
Variables
{
  "page": 987,
  "perPage": 123,
  "sortField": "xyz789",
  "sortOrder": "xyz789",
  "filter": ProjectFilter
}
Response
{
  "data": {
    "allProjects": [
      {"id": 123, "name": "abc123"}
    ]
  }
}
Queries

allRecordTypes

Description

Get a all the Record Types

Response

Returns [RecordType!]!

Arguments
Name Description
page - Int
perPage - Int
sortField - String
sortOrder - String
filter - RecordTypeFilter

Example

Query
query allRecordTypes(
  $page: Int,
  $perPage: Int,
  $sortField: String,
  $sortOrder: String,
  $filter: RecordTypeFilter
) {
  allRecordTypes(
    page: $page,
    perPage: $perPage,
    sortField: $sortField,
    sortOrder: $sortOrder,
    filter: $filter
  ) {
    id
    name
    category
    sub_category
    order
    descriptions {
      ...DescriptionFragment
    }
  }
}
Variables
{
  "page": 123,
  "perPage": 123,
  "sortField": "abc123",
  "sortOrder": "abc123",
  "filter": RecordTypeFilter
}
Response
{
  "data": {
    "allRecordTypes": [
      {
        "id": 123,
        "name": "xyz789",
        "category": "xyz789",
        "sub_category": "xyz789",
        "order": 123,
        "descriptions": [Description]
      }
    ]
  }
}
Queries

allRecords

Description

Get a list of Records

Response

Returns [Record!]!

Arguments
Name Description
page - Int
perPage - Int
sortField - String
sortOrder - String
filter - RecordFilter

Example

Query
query allRecords(
  $page: Int,
  $perPage: Int,
  $sortField: String,
  $sortOrder: String,
  $filter: RecordFilter
) {
  allRecords(
    page: $page,
    perPage: $perPage,
    sortField: $sortField,
    sortOrder: $sortOrder,
    filter: $filter
  ) {
    id
    record_id
    project {
      ...ProjectFragment
    }
    record_type {
      ...RecordTypeFragment
    }
    values {
      ...RecordValueFragment
    }
    value {
      ...RecordValueFragment
    }
    attachments {
      ...AttachmentFragment
    }
    childLink {
      ...LinkFragment
    }
    parentLink {
      ...LinkFragment
    }
  }
}
Variables
{
  "page": 123,
  "perPage": 123,
  "sortField": "xyz789",
  "sortOrder": "abc123",
  "filter": RecordFilter
}
Response
{
  "data": {
    "allRecords": [
      {
        "id": 987,
        "record_id": "xyz789",
        "project": Project,
        "record_type": RecordType,
        "values": [RecordValue],
        "value": RecordValue,
        "attachments": [Attachment],
        "childLink": [Link],
        "parentLink": [Link]
      }
    ]
  }
}
Queries

allTrades

Response

Returns [Trade]!

Arguments
Name Description
page - Int
perPage - Int
sortField - String
sortOrder - String
filter - TradeFilter

Example

Query
query allTrades(
  $page: Int,
  $perPage: Int,
  $sortField: String,
  $sortOrder: String,
  $filter: TradeFilter
) {
  allTrades(
    page: $page,
    perPage: $perPage,
    sortField: $sortField,
    sortOrder: $sortOrder,
    filter: $filter
  ) {
    id
    name
    created_at
    updated_at
  }
}
Variables
{
  "page": 123,
  "perPage": 123,
  "sortField": "xyz789",
  "sortOrder": "xyz789",
  "filter": TradeFilter
}
Response
{
  "data": {
    "allTrades": [
      {
        "id": 123,
        "name": "abc123",
        "created_at": "abc123",
        "updated_at": "xyz789"
      }
    ]
  }
}
Queries

getRecordTypeTemplates

Response

Returns [RecordType!]!

Example

Query
query getRecordTypeTemplates {
  getRecordTypeTemplates {
    id
    name
    category
    sub_category
    order
    descriptions {
      ...DescriptionFragment
    }
  }
}
Response
{
  "data": {
    "getRecordTypeTemplates": [
      {
        "id": 987,
        "name": "abc123",
        "category": "xyz789",
        "sub_category": "abc123",
        "order": 123,
        "descriptions": [Description]
      }
    ]
  }
}

Mutations

Mutations

createProject

Response

Returns a CreateProjectResponse!

Arguments
Name Description
createProjectInput - CreateProjectInput

Example

Query
mutation createProject($createProjectInput: CreateProjectInput) {
  createProject(createProjectInput: $createProjectInput) {
    project {
      ...ProjectFragment
    }
    companyProjectId
  }
}
Variables
{"createProjectInput": CreateProjectInput}
Response
{
  "data": {
    "createProject": {
      "project": Project,
      "companyProjectId": 987
    }
  }
}
Mutations

createRecords

Description

Create one or many Records

Response

Returns [Record]!

Arguments
Name Description
project_id - Int!
createRecordsInput - [CreateRecordInput!]!

Example

Query
mutation createRecords(
  $project_id: Int!,
  $createRecordsInput: [CreateRecordInput!]!
) {
  createRecords(
    project_id: $project_id,
    createRecordsInput: $createRecordsInput
  ) {
    id
    record_id
    project {
      ...ProjectFragment
    }
    record_type {
      ...RecordTypeFragment
    }
    values {
      ...RecordValueFragment
    }
    value {
      ...RecordValueFragment
    }
    attachments {
      ...AttachmentFragment
    }
    childLink {
      ...LinkFragment
    }
    parentLink {
      ...LinkFragment
    }
  }
}
Variables
{
  "project_id": 123,
  "createRecordsInput": [CreateRecordInput]
}
Response
{
  "data": {
    "createRecords": [
      {
        "id": 987,
        "record_id": "abc123",
        "project": Project,
        "record_type": RecordType,
        "values": [RecordValue],
        "value": RecordValue,
        "attachments": [Attachment],
        "childLink": [Link],
        "parentLink": [Link]
      }
    ]
  }
}
Mutations

deleteRecords

Description

Delete one or many Records

Response

Returns an Int!

Arguments
Name Description
filter - RecordFilter!
sourceApp - String
sourceDevice - String

Example

Query
mutation deleteRecords(
  $filter: RecordFilter!,
  $sourceApp: String,
  $sourceDevice: String
) {
  deleteRecords(
    filter: $filter,
    sourceApp: $sourceApp,
    sourceDevice: $sourceDevice
  )
}
Variables
{
  "filter": RecordFilter,
  "sourceApp": "abc123",
  "sourceDevice": "abc123"
}
Response
{"data": {"deleteRecords": 123}}
Mutations

updateRecords

Description

Update one or many Records

Response

Returns an Int

Arguments
Name Description
filter - RecordFilter!
values - [RecordValueUpdate!]!
sourceApp - String
sourceDevice - String

Example

Query
mutation updateRecords(
  $filter: RecordFilter!,
  $values: [RecordValueUpdate!]!,
  $sourceApp: String,
  $sourceDevice: String
) {
  updateRecords(
    filter: $filter,
    values: $values,
    sourceApp: $sourceApp,
    sourceDevice: $sourceDevice
  )
}
Variables
{
  "filter": RecordFilter,
  "values": [RecordValueUpdate],
  "sourceApp": "xyz789",
  "sourceDevice": "abc123"
}
Response
{"data": {"updateRecords": 987}}

Types

Attachment

Description

Represents a user-uploaded file associated with a record, including its metadata and access information

Fields
Field Name Description
id - Int! Unique identifier for the attachment
format - String! MIME type of the attachment (e.g., 'image/jpeg', 'application/pdf')
data - String Base64-encoded string of the attachment data
url - String Signed URL where the attachment can temporarily be downloaded
Example
{
  "id": 987,
  "format": "abc123",
  "data": "xyz789",
  "url": "xyz789"
}
Types

Boolean

Description

The Boolean scalar type represents true or false

Types

CreateProjectInput

Fields
Input Field Description
name - String!
copyOf - Int
copyRecordTypeIds - [Int]
Example
{
  "name": "xyz789",
  "copyOf": 987,
  "copyRecordTypeIds": [123]
}
Types

CreateProjectResponse

Fields
Field Name Description
project - Project!
companyProjectId - Int!
Example
{"project": Project, "companyProjectId": 987}
Types

CreateRecordInput

Fields
Input Field Description
record_type_id - Int!

Type ID for this record. Eg: 1234
record_id - String!

Humanized Record ID eg: Window 001
values - [RecordValueCreate!]

Object contains properties descriptionID and value
Example
{
  "record_type_id": 123,
  "record_id": "abc123",
  "values": [RecordValueCreate]
}
Types

Date

Description

Date custom scalar type

Example
"2007-12-03"
Types

Description

Fields
Field Name Description
id - Int!
recordType - RecordType!
name - String!
type - String!
order - Int
listValues - [ListValue!]
Example
{
  "id": 987,
  "recordType": RecordType,
  "name": "abc123",
  "type": "abc123",
  "order": 987,
  "listValues": [ListValue]
}
Types

FitEnum

Description

Enum for image resizing strategies

Values
Enum Value Description

contain

 Preserves aspect ratio; fits within given dimensions

cover

 Preserves aspect ratio; fills the given dimensions

fill

 Does not preserve aspect ratio; stretches to fill dimensions

inside

 Preserves aspect ratio; fits within given dimensions, without cropping

outside

 Preserves aspect ratio; fills given dimensions, may overflow
Example
"contain"
Types

ImageResize

Description

Input type for resizing an image

Fields
Input Field Description
width - Int

Width of the image in pixels
height - Int

Height of the image in pixels
fit - FitEnum

Resize strategy
Example
{"width": 987, "height": 123, "fit": "contain"}
Types

Int

Description

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1

Example
987
Types

LinkInput

Fields
Input Field Description
primary_record_id - Int!

Primary record id
secondary_record_id - Int!

Secondary record id
Example
{"primary_record_id": 123, "secondary_record_id": 987}
Types

ListMetadata

Fields
Field Name Description
count - Int!
Example
{"count": 123}
Types

ListValue

Fields
Field Name Description
id - Int!
value - String!
order - Int!
Example
{"id": 123, "value": "xyz789", "order": 123}
Types

Project

Fields
Field Name Description
id - Int! The matrak Internal ID of the project
name - String! The name of the project
Example
{"id": 123, "name": "xyz789"}
Types

ProjectFilter

Fields
Input Field Description
id - Int
ids - [Int]
name - String
name__like - String
company_id - Int
address - String
address__like - String
owner - String
owner__like - String
contact_details - String
contact_details__like - String
comments - String
comments__like - String
start_date - String
start_date__gte - Date
start_date__lte - Date
start_date__like - String
end_date - String
end_date__gte - Date
end_date__lte - Date
end_date__like - String
created_at - String
created_at__gte - Date
created_at__lte - Date
created_at__like - String
updated_at - String
updated_at__like - String
classification - String
classification__in - [String]
hubspot_id - String
hubspot_ids - [String]
bci_id - String
bci_ids - [String]
is_archived - Boolean
archived_at - String
archived_at__gte - Date
archived_at__lte - Date
archived_at__like - String
user_access - Int

Filter by user access, currently super user bahaviour is not implemented, same as normal user
Example
{
  "id": 123,
  "ids": [123],
  "name": "xyz789",
  "name__like": "xyz789",
  "company_id": 123,
  "address": "xyz789",
  "address__like": "abc123",
  "owner": "abc123",
  "owner__like": "abc123",
  "contact_details": "abc123",
  "contact_details__like": "xyz789",
  "comments": "xyz789",
  "comments__like": "xyz789",
  "start_date": "abc123",
  "start_date__gte": "2007-12-03",
  "start_date__lte": "2007-12-03",
  "start_date__like": "xyz789",
  "end_date": "xyz789",
  "end_date__gte": "2007-12-03",
  "end_date__lte": "2007-12-03",
  "end_date__like": "xyz789",
  "created_at": "xyz789",
  "created_at__gte": "2007-12-03",
  "created_at__lte": "2007-12-03",
  "created_at__like": "xyz789",
  "updated_at": "xyz789",
  "updated_at__like": "abc123",
  "classification": "abc123",
  "classification__in": ["abc123"],
  "hubspot_id": "xyz789",
  "hubspot_ids": ["xyz789"],
  "bci_id": "abc123",
  "bci_ids": ["xyz789"],
  "is_archived": false,
  "archived_at": "xyz789",
  "archived_at__gte": "2007-12-03",
  "archived_at__lte": "2007-12-03",
  "archived_at__like": "xyz789",
  "user_access": 987
}
Types

Record

Fields
Field Name Description
id - Int! The globally unique ID for a record eg: 100023
record_id - String Humanized Record ID eg: Window 001
project - Project The details of the project this record belongs to, e.g. Melbourne Hotel
record_type - RecordType! Type details for this record. E.g. Joinery
values - [RecordValue!]! An array of values that this record has, e.g: WIN-0001, Complete
Arguments
description - String
value - RecordValue Get a specific value for a record
Arguments
description - String!
attachments - [Attachment!]! An array of attachments that this record has
Arguments
imageResize - ImageResize
childLink - [Link] Child materials that belong to this record
parentLink - [Link] Parent materials that belong to this record
Example
{
  "id": 123,
  "record_id": "abc123",
  "project": Project,
  "record_type": RecordType,
  "values": [RecordValue],
  "value": RecordValue,
  "attachments": [Attachment],
  "childLink": [Link],
  "parentLink": [Link]
}
Types

RecordFilter

Fields
Input Field Description
ids - [Int]

Filter records that are passed in the array of IDS
id - Int

Filter record by internal database id. This is different than the 'ID' description on the actual record. The internal database ID is what is returned in the 'id' field of a Record
record_id - String

Filter records exactly matching this 'ID' description value. This is different than the internal database ID
record_ids - [String]

Filter record exactly matching this 'ID' description value. This is different than the internal database ID
record_type_name - String

Filter records that have this record type name
record_type_id - Int

Filter records that have this record type id
record_type_ids - [Int]

Filter records that have this record type ids
record_value - RecordFilterByRecordValueFilter

Filter the records to those containing a certain record value
record_values - RecordFilterByRecordValuesFilter

Filter the records to those each of these record values
project_name - String

Filter the records to a specific project by name
project_id - Int

Filter the records that are part of a specific project by id
Example
{
  "ids": [987],
  "id": 987,
  "record_id": "xyz789",
  "record_ids": ["abc123"],
  "record_type_name": "xyz789",
  "record_type_id": 123,
  "record_type_ids": [987],
  "record_value": RecordFilterByRecordValueFilter,
  "record_values": RecordFilterByRecordValuesFilter,
  "project_name": "xyz789",
  "project_id": 987
}
Types

RecordFilterByRecordValueFilter

Fields
Input Field Description
value - String

Filter record by its value
description_name - String

Filter record by its description name
values - [String]

Filter records by an array of values
Example
{
  "value": "abc123",
  "description_name": "xyz789",
  "values": ["xyz789"]
}
Types

RecordFilterByRecordValuesFilter

Fields
Input Field Description
values - [RecordFilterByRecordValueFilter]

Object containing possible properties to filter by
Example
{"values": [RecordFilterByRecordValueFilter]}
Types

RecordType

Fields
Field Name Description
id - Int!
name - String!
category - String!
sub_category - String
order - Int!
descriptions - [Description!]!
Example
{
  "id": 987,
  "name": "abc123",
  "category": "xyz789",
  "sub_category": "xyz789",
  "order": 123,
  "descriptions": [Description]
}
Types

RecordTypeCategory

Values
Enum Value Description

container

material

location

delivery

task

subtask
Example
"container"
Types

RecordTypeFilter

Fields
Input Field Description
ids - [Int]
project_id - Int
category - RecordTypeCategory
Example
{"ids": [987], "project_id": 123, "category": "container"}
Types

RecordValue

Fields
Field Name Description
id - Int! A globally unique identifier for this Record Value
value - String! The value of a record
description - Description! The description details of this record value, e.g. name: ID, type: text
Example
{
  "id": 987,
  "value": "xyz789",
  "description": Description
}
Types

RecordValueCreate

Fields
Input Field Description
description_id - Int!

Specific the existing description ID eg: Status is ID: 20
value - String!

Value of the description eg: Completed
Example
{"description_id": 123, "value": "abc123"}
Types

RecordValueUpdate

Fields
Input Field Description
description_name - String

Specify either a specific description, or descriptions matching a name for which this record update should apply for
description_id - Int

Specific the existing description ID
value - String!

The new record value to apply
updateChildren - Boolean

Mark this update to be applied to materials/subcomponents contained withing this record
Example
{
  "description_name": "xyz789",
  "description_id": 123,
  "value": "xyz789",
  "updateChildren": false
}
Types

RecordsUpdatedEvent

Fields
Field Name Description
ids - [Int!]!
updates - [UpdateRecordsArgs!]!
Example
{"ids": [987], "updates": [UpdateRecordsArgs]}
Types

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text

Example
"xyz789"
Types

Trade

Fields
Field Name Description
id - Int!
name - String!
created_at - String
updated_at - String
Example
{
  "id": 987,
  "name": "abc123",
  "created_at": "abc123",
  "updated_at": "xyz789"
}
Types

TradeFilter

Fields
Input Field Description
id - Int
ids - [Int]
name - String
name__like - String
created_at - String
created_at__like - String
updated_at - String
updated_at__like - String
Example
{
  "id": 123,
  "ids": [987],
  "name": "xyz789",
  "name__like": "abc123",
  "created_at": "abc123",
  "created_at__like": "abc123",
  "updated_at": "abc123",
  "updated_at__like": "xyz789"
}
Types

UpdateRecordsArgs

Fields
Field Name Description
description_id - Int
description_name - String
value - String!
Example
{
  "description_id": 987,
  "description_name": "xyz789",
  "value": "xyz789"
}

Subscriptions

recordsUpdated

Response

Returns a RecordsUpdatedEvent

Arguments
Name Description
project_id - Int!

Example

Query
subscription recordsUpdated($project_id: Int!) {
  recordsUpdated(project_id: $project_id) {
    ids
    updates {
      ...UpdateRecordsArgsFragment
    }
  }
}
Variables
{"project_id": 123}
Response
{
  "data": {
    "recordsUpdated": {
      "ids": [987],
      "updates": [UpdateRecordsArgs]
    }
  }
}

importBatchUpdated

Description

Subscribe to real-time updates for import batch processing status changes. This subscription notifies clients when an import batch's status changes (e.g., from processing to ready for import, or when import execution completes). Useful for building real-time UI updates for import progress tracking.

Arguments
Name Description
project_id - Int! The project ID to filter import batch updates for. Only batches belonging to this project will trigger notifications.
Response

Returns an ImportBatchUpdatedEvent containing the updated import batch object and event metadata.

ImportBatchUpdatedEvent Fields:
  • importBatch: The updated ImportBatch object with current status
  • eventType: Type of update (e.g., "status_change", "processing_complete")
  • timestamp: When the update occurred
Security
  • Requires JWT authentication via WebSocket connection
  • User must have READ access to the specified project
  • Only receives updates for batches the user has access to

Example

Subscription
subscription importBatchUpdated($project_id: Int!) {
  importBatchUpdated(project_id: $project_id) {
    importBatch {
      id
      status
      fk_project_id
      created_records
      updated_records
      linked_records
      completed_at
      updated_at
    }
    eventType
    timestamp
  }
}
Variables
{
  "project_id": 123
}
Response
{
  "data": {
    "importBatchUpdated": {
      "importBatch": {
        "id": 456,
        "status": "READY_TO_IMPORT",
        "fk_project_id": 123,
        "created_records": null,
        "updated_records": null,
        "linked_records": null,
        "completed_at": null,
        "updated_at": "2024-01-15T11:30:00.000Z"
      },
      "eventType": "processing_complete",
      "timestamp": "2024-01-15T11:30:00.000Z"
    }
  }
}
Endpoints

GET /attachment/:id

Description

Streams a file based on the attachment ID.

Path Parameters
Parameter Type Description
id number The ID of the attachment to be streamed.
Response

Returns the file content as a binary stream with appropriate Content-Type header.

  • 200 OK: The file content streamed directly to the response.
  • 401 Unauthorized: If the authentication token is invalid or missing.
  • 403 Forbidden: If the user does not have read access.
  • 404 Not Found: If the attachment with the given ID does not exist.
Endpoints

POST /attachment/

Description

Uploads a new attachment.

Headers
Header Type Description
Content-Type multipart/form-data Indicates that the request body contains a file upload.
Request Body
Field Type Description
file file The file to be uploaded.
recordIds number[] An array of integer record IDs associated with the attachment.
Response

Returns an array of attachment IDs for the uploaded file.

200 OK: Returns an array of attachment IDs (one for each record ID provided).

[123, 124]
Error Responses:
  • 400 Bad Request: If no file is provided, no recordIds are provided, file exceeds 75MB limit, or unsupported file type.
  • 401 Unauthorized: If the authentication token is invalid or missing.
  • 403 Forbidden: If the user does not have write access to the specified records.
  • 404 Not Found: If one or more of the provided recordIds are invalid.
Endpoints

POST /import/upload

Description

Upload one or more files for processing into an Import Batch. Files are preprocessed, validated, and transformed asynchronously in the background. The endpoint returns immediately with the Import Batch object while processing continues. If the file matches the system import format, AI processing is skipped; otherwise a best-fit import configuration may be selected or generated and AI analysis performed. Result files and optional error reports are produced. Set applyChanges to import automatically after processing.

Headers
Header Type Description
Content-Type multipart/form-data Indicates that the request body contains a multi-part upload.
Authorization Bearer {token} JWT authentication token required for access.
Request Body
Field Type Description
{any_field_name} file[] One or more files to upload and process. Field name can be any name (e.g., "files", "attachments", etc.). Accepts CSV, XLSX, XLS, and PDF formats.
importBatchId number Optional. Existing import batch ID to attach these files to. Required if createWithNewBatch is not provided.
createWithNewBatch JSON string Optional. JSON object (send as a JSON string in multipart forms) to create a new import batch when importBatchId is not provided. Fields:
  • projectId (number, required): Project ID for the import batch
applyChanges boolean Optional. If true, automatically executes the import after processing completes. Default: false.
source string Optional. Source label (e.g., web, api) to identify the origin of the upload.
Security
  • Requires JWT authentication
  • User must have WRITE access to the target project
Response

Returns an Import Batch object immediately while file processing continues in the background.

200 OK: Import Batch object with the following structure:

{
  "id": 123,
  "fk_user_id": 456,
  "fk_company_id": 789,
  "fk_project_id": 101,
  "status": "NOT_READY_TO_IMPORT",
  "source": null,
  "name": null,
  "metadata": {
    "projectId": 101
  },
  "created_records": null,
  "updated_records": null,
  "linked_records": null,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z",
  "completed_at": null,
  "import_result_id": null
}
Import Batch Status Values:
  • NOT_READY_TO_IMPORT: Files are being processed
  • READY_TO_IMPORT: Processing complete, ready for import execution
  • IMPORT_IN_PROGRESS: Import is currently running
  • IMPORT_COMPLETED: Import finished successfully
  • IMPORT_FAILED: Import failed with errors

Note: Processing happens asynchronously. Use the batch ID to query for result files and processing status updates via other endpoints.

Example

cURL Request
curl -X POST https://api.matrak.com/import/upload \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "files=@materials.xlsx" \
  -F "createWithNewBatch={\"projectId\":123}" \
  -F "applyChanges=false"
JavaScript (FormData)
const formData = new FormData();
formData.append('files', fileInput.files[0]);
formData.append('createWithNewBatch', JSON.stringify({
  projectId: 123
}));
formData.append('applyChanges', 'false');

const response = await fetch('/import/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  },
  body: formData
});

const importBatch = await response.json();
Python (requests)
import requests
import json

url = "https://api.matrak.com/import/upload"
headers = {
    "Authorization": "Bearer YOUR_JWT_TOKEN"
}

files = {
    'files': ('materials.xlsx', open('materials.xlsx', 'rb'))
}

data = {
    'createWithNewBatch': json.dumps({"projectId": 123}),
    'applyChanges': 'false'
}

response = requests.post(url, headers=headers, files=files, data=data)
import_batch = response.json()
Response Example
{
  "id": 123,
  "fk_user_id": 456,
  "fk_company_id": 789,
  "fk_project_id": 123,
  "status": "NOT_READY_TO_IMPORT",
  "source": null,
  "name": null,
  "metadata": {
    "projectId": 123
  },
  "created_records": null,
  "updated_records": null,
  "linked_records": null,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z",
  "completed_at": null,
  "import_result_id": null
}
Endpoints

POST /private/activity/export/materials

Description

This endpoint exports material history as a CSV file. It requires authentication and READ access level. The response will be returned as a CSV file containing material transfer history for the specified project.

Request Body
Field Type Description
projectId Int The ID of the project to export materials from
Response

Returns a CSV file containing the following columns:

  • history_material_id
  • formatted_timestamp
  • first_name
  • last_name
  • company_name
  • record_type
  • category
  • record_id
  • action
  • prev_project
  • new_project
Security
  • Requires JWT authentication
  • Minimum access level: READ
Endpoints

POST /private/activity/export/descriptions

Description

This endpoint exports material description values history as a CSV file. It requires authentication and READ access level. The response will be returned as a CSV file containing material description changes and history.

Request Body
Field Type Description
projectId Int The ID of the project to export description values from
Response

Returns a CSV file containing material description history data with the following information:

  • transaction_id
  • timestamp
  • first_name
  • last_name
  • company_name
  • record_type
  • category
  • record_id
  • action
  • description
  • prev_value
  • new_value
Security
  • Requires JWT authentication
  • Minimum access level: READ
Endpoints

POST /private/activity/export/transfers

Description

This endpoint exports material transfer history as a CSV file. It specifically focuses on transfer events (TRANSFER_IN and TRANSFER_OUT actions) between projects. It requires authentication and READ access level.

Request Body
Field Type Description
projectId Int The ID of the project to export transfer history from
Response

Returns a CSV file containing transfer history with the following columns:

  • transaction_id
  • timestamp
  • first_name
  • last_name
  • company_name
  • record_type
  • category
  • record_id
  • action (TRANSFER_IN/TRANSFER_OUT)
  • description
  • prev_value
  • new_value
Security
  • Requires JWT authentication
  • Minimum access level: READ
Additional Notes
  • The endpoint combines both material transfer records and description transfer records