Getting Started with Buildxact APIs

This page describes how to get access to our REST APIs.

Creating a subscription key

A subscription key identifies your company to our API, so that we know who is making the requests. You only need a single subscription key to access all our APIs and for all data that you may need to access - you do not need to request multiple subscription keys!

1.       Follow the Sign In or Sign Up links in the navbar.

2.       Select a Plan and request a Subscription. When asked for a subscription name, please provide the name of your company. This assists us to verify that you are an existing customer or partner of Buildxact.

3.       When you submit the subscription request, it will be sent through to our team for approval

4.       When our team approves it, you will receive a confirmation email. At this point you can go to your profile page and you will find a Primary and Secondary subscription key there. Both the Primary and Secondary keys have the same permissions; we provide two in case you wish to rotate them.

The subscription key is a secret key for use by your organization, and must then be passed in an HTTP header Ocp-Apim-Subscription-Key to all HTTP requests.

This key is permanent but should be kept in a secrets store in your system (for example, Azure Key Vault).

Logging into the API to access data

When your system needs to make a call into our APIs, you need to begin by obtaining a bearer token for your session, that can be used to access your tenant data.

Please see the Authorization page for information about how this works.

Our API applies rate limiting to ensure fair usage, and you will receive a 429 response code if too many requests are made in a short time. This can be resolved by retrying with a delay. Our rate limits allow you to make 100 HTTP requests within a 30 second period.

What headers do I need to set in my request?


To call our APIs, you will need to include the following headers:

1.       Ocp-Apim-Subscription-Key (as described above)

2.       Authorization ('Authorization' : 'Bearer {{TOKEN}}')

The Authorization header is generated upon user authentication/authorization. More details about this can be found on our Authentication page.

The subscription key header should be provided on each request to the API, except the token and authorize endpoints.

Are you a supplier looking to automate your price file integration?

Please read our Price file automation for suppliers guide to get started.

Staging Environment

A Staging environment is available that you can use whilst developing your integration for testing. It is on the following URL:

https://developer-uat.buildxact.com/signup

The staging environment has separate subscription keys, hence you must request a subscription in Staging as well as in production, each environment has a different key.

While testing, you may wish to use Buildxact's Staging UI to test your work. You can log in here:

https://app-staging.buildxact.com/

You can create a builder login for Staging by following this link: https://app-staging.buildxact.com/au/signup.html

NOTE: The terms “UAT” and “Staging” are used interchangeably and refer to the same environment.

OData

Many of our REST endpoints support OData, to enable you to filter and sort data based on your requirements.

This includes running filters such as:

  • contains [on string fields -> contains(clientName, 'Terry')]

  • greater [totalIncTax gt 98000]

  • lower [totalIncTax lt 37500]

  • equal [totalIncTax eq 750000]

  • in [status in ('Revoked','NotConnected')]

You can combine multiple of these filters with and\or, for example, when searching for Jobs that have the client name of John Wertheim, we can do the following OData query: contains(clientName, 'John') and contains(clientName, ' Werth'). Some additional examples of OData queries will be presented further down in this section.

Sorting can be done on most of the fields presented on the response object and can be done as follows: $orderBy=createdDate desc, $orderBy=clientName ASC etc.

When calling the OData endpoints, to retrieve the total number of available records, you need to include the $count=true property in the query string. The response will then contain a header with the total record count. The header name is ‘x-odata-total-count’. If $count=true is not present or you’ve used $count=false, this header will not be returned.

Paging in OData can be done by utilizing the $top=X, $skip=Y and $count=true\false. X is the number of records you want to select, whereas Y is the number of records you want to skip. When paging, first page would be: $top=5&$skip=0, second page $top=5&$skip=5, third page $top=5&$skip=10 etc. As we can see, only the $skip value changes, and once you have paged through all the data (see more information on the total count paragraph below), you will no longer receive any items. It is recommended that you do not request data past the total count point. In cases where $skip is not provided, its presumed to be as $skip=0.

Skip (Y) = Top (X) * (Page Number – 1)

Some sample OData request queries:

Migrating from Buildxact API v1 and v2

The new API utilizes the OData Protocol (more details in the next section) and calls to it are done differently to what you have previously done with the existing APIs which are going to be deprecated soon:

V1 - https://api.buildxact.com/docs/ui/index

V2 - https://api.buildxact.com/rest/docs

Field Omissions

Some of objects that existed on the old APIs are not available on the new one. Those will be listed below. These are all properties on objects returned by the /catalogues endpoints.

IncomingCatalogueDto\CatalogueDto

activeItemCount, createdByUsername, importProgress, modifiedByUsername, supplierDescription

CatalogueItemDto

catalogueCategory, catalogueSubCategory, createdByUsername, modifiedByUsername, recipeItems

IntegrationConnectionDto

createdByUsername, modifiedByUsername, acceptedByUsername, rejectedByUsername, revokedByUsername

AccessControlExtendedDto

acceptedByUsername, createdByUsername, modifiedByUsername, rejectedByUsername, revokedByUsername

Affected Endpoints

The endpoints listed below with brackets around them [IntegrationConnectionDto] refer to arrays.

  • Incoming Integration Connections

    • List incoming connections ([IntegrationConnectionDto])

    • List incoming connection counts (]IntegrationConnectionStatusCountDto]) - Unaffected

    • List catalogues for incoming connection (IncomingCatalogueDto)

    • Get incoming connection (IntegrationConnectionDto)

    • Accept request (IntegrationConnectionDto)

    • Reject request (IntegrationConnectionDto)

    • Revoke connection (IntegrationConnectionDto)

  • Access Controls

    • List access controls ([AccessControlExtendedDto])

    • Add\Delete\Recover - Unaffected as they use AccessControlSimpleDto (dto contains same fields as rest gateway endpoint)

  • Categories - Unaffected

  • Catalogues

    • List ([CatalogueDto])

    • Get by Id (CatalogueDto)

    • Add\Update (CatalogueDto)

    • Delete\Recover - Unaffected (bool response)

  • Catalogue Items

    • Get Items ([CatalogueItemDto])

    • Get Item (CatalogueItemDto)

    • Add\Delete\Update\Recover (CatalogueItemDto)

    • Search - Unaffected

  • Import

    • Start - Unaffected

    • Get by Id - Unaffected

    • Import Items - Unaffected

  • Estimates

    • Creation - Consolidation of customer/client details into CustomerCreateOptions instead of having customer attributes as primitives on Estimate create request body itself.