Overview

Buildxact uses token based authentication when communicating with our API. You will need to first obtain a token by providing the necessary login details, then use that token for every call you make to the API. Tokens have a limited lifetime of 24 hours, after which, you can log in again to obtain a new token, or refresh an existing one.

There are no limits at present on the amount of calls you can make to our API, but we do expect you to write efficient integration code and plan carefully how often you require data.

Some API endpoints can return a large amount of data, and in most cases, these endpoints support OData query options for you to limit and filter the data received.

For information on how to use OData queries, please see http://www.odata.org/getting-started/basic-tutorial#queryData


Tenants

Buildxact uses a multi-tenanted data store. Tenants are companies that have access to Buildxact. Your login will determine how much data you can access using the API endpoints. To see this, you can make a GET request to https://api-v1.buildxact.com.au/accounts/tenants to view all the tenant data you will receive when making calls to retrieve Estimates for example. Each estimate will have a tenantId which will show which company the estimate belongs too.

In general, most API users will have access to their own accounts. However, as an example, a franchise user may have access to all tenants within that franchise.

You should take this into consideration when designing any integration code.


Obtaining a token

REQUEST

POST:         https://api-v1.buildxact.com.au/oauth/token
Content-Type: application/x-www-form-urlencoded
Body: username=<username>&password=<password>& grant_type=password&client_id=<clientid>&client_secret=<clientsecret>

Body Parameters

<username>     Your Buildxact user name
<password> Your Buildxact password
<clientid> API client id as provided by Buildxact
<clientsecret> API client secret/password as provided by Buildxact

RESPONSE

{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJieDp1aWQiOiJHUjM3Q0d2ajZWMThJdzFMKzZqaTRsN0pnL29wS3ZveTduVnc4SEthd2N3L0thZXBYa29IeWxMZU9uUEtTWGhkIiwiYng6dGlkIjoiRGk1ZGxoRmUrL1BBN2RyRFJ5RTd3UW5aTDdDTFV1NXVZWmlEcjhzU3NyVzBZemZUUGxMRXQ3c0Q0ZEhtSk83dSIsImJ4OmFkIjoiOVgxeU13bVdjd2VJSFcrc0lKWVRYQT09IiwiYng6ZXgiOiJCVDdWL04wSjI0MmZoOUxxQlJ4WldtYnZidFN0V3JsZ0dOSGhzd1crdGcwPSIsImJ4OmZpZCI6Im51bGwiLCJieDpmYWlkIjoibnVsbCIsImJ4OnVyIjoiT1A0SVB6Z3czelNkcGJlTDV3cDlEUT09Iiwicm9sZSI6IlRlbmFudFVzZXIiLCJpc3MiOiJhcGktdjEuYnVpbGR4YWN0LmNvbS5hdSIsImF1ZCI6ImMxZjhiNjhkNWMyMTRlMjQ4MmE5YjY1NGJlMWUzM2Y2IiwiZXhwIjoxNDUwODI5NjYyLCJuYmYiOjE0NTA3NDMyNjJ9.kUIac0HiQUUCUGc64OSDCTRuaJPSPz75sgRum4hfPN0",
"token_type": "bearer",
"expires_in": 86399,
"refresh_token": "42f3df53a67c42d9b2246f95f086eecc"
}

expires_in: Total seconds access token is valid for

refresh_token: Can be used to refresh this access token


Using access token

For all calls to the Buildxact API, you must supply the access token value as an Authorization Header on the request:

GET:           https://api-v1.buildxact.com.au/estimates
Authorization: bearer <access_token>

Ensure the value for the Authorization header begins with 'bearer', followed by a space, then the access_token value you received.


Obtaining an impersonation token

When requesting a token, you can specify the ID of a tenant you would like access to other than the one your user account is related to. You may have access to other tenant data as part of your account set up (particularly if you are a franchise). To facilitate this, pass in the tenant ID you are requesting access to along with your login credentials.

REQUEST

POST:         https://api-v1.buildxact.com.au/oauth/token
Content-Type: application/x-www-form-urlencoded
Body: username=<username>&password=<password>& grant_type=password&client_id=<clientid>&client_secret=<clientsecret>&tenant_id=<tenantId>

Body Parameters

<username>     Your Buildxact user name
<password> Your Buildxact password
<clientid> API client id as provided by Buildxact
<clientsecret> API client secret/password as provided by Buildxact
<tenantId> Tenant Id Guid you are requesting access to.

If you need to know the tenant ID’s you can access, take these steps first to determine what you can access:

  1. Obtain a login token as per normal (without tenant Id)
  2. Using that token, make a GET request to accounts/tenants which will return the tenants you have access to
  3. Request a new token using your original username and password, along with the tenant Id you want to access

Once you receive the impersonation token, any calls to the API will return data associated with tenant Id you now have access to, instead of the one related to your user.


API Endpoints

For documentation on all endpoints available, and the data returned, please visit:

https://api-v1.buildxact.com.au/docs/ui/index


Refresh a token

When you obtain a token, you are also provided with a refresh_token value. This can be used to renew your original access_token before it expires. Refresh tokens are optional, as you can simply obtain a new token with your user name and password as before.

REQUEST

POST:         https://api-v1.buildxact.com.au/oauth/token
Content-Type: application/x-www-form-urlencoded
Body: refresh_token=<refreshtoken>&grant_type=refresh_token&client_id=<clientid>&client_secret=<clientsecret>

Body Parameters

<refreshtoken> Refresh token value received when obtaining access token
<clientid> API client id as provided by Buildxact
<clientsecret> API client secret/password as provided by Buildxact
Did this answer your question?