Audience: builders/suppliers
Read time: 10 mins
Article contents: How to authenticate and start using Buildxact API
Special Notice
This API was deprecated on November 1, 2023 and is no longer supported. It will be fully shut down on September 2, 2024. It is recommended to migrate to the new version of the API to ensure uninterrupted service and access to new features.
For more information and migration guidelines, please refer to the documentation at: https://developer.buildxact.com/getting-started
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
Requesting access
Please get in touch with our support team who will be able to setup API access for your account.
You can contact the team by either emailing [email protected] or by starting a chat with us.
If you could please provide your preferred email as well, as we will send the details to this supplied email address.
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.buildxact.com/accounts/tenants to view all the tenant data you will receive when making calls to retrieve Estimates for example. Each estimate will have a tenant ID 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
Buildxact provides an OAuth-based token mechanism, with long-lived refresh tokens and short-lived bearer tokens (also known as “access tokens”).
Please note that when you obtain a token, it is valid for a period of time and can be used until it expires. Please code your logic to check the expires_infield shown below and persist the token until it expires (as per OAuth standards, the expires_infield is the number of seconds that the token is valid for).
Buildxact will not allow you to have more than 200 active refresh tokens; if you generate more than this, the oldest one will automatically be deactivated.
Do not attempt to request a new token for every API request –please use the one you already have if it is still valid!
REQUEST
POST: https://api.buildxact.com/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
<Grant_type> "password"
<client_id> API client id as provided by Buildxact
<client_secret> API client secret/password as provided by Buildxact
RESPONSE
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJie....",
"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.buildxact.com/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.buildxact.com/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 what tenant IDs you can access, take these steps:
Obtain a login token as per normal (without tenant ID)
Using that token, make a GET request to accounts/tenants which will return the tenants you have access to
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:
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 username and password as before.
REQUEST
POST: https://api.buildxact.com/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
<refresh_token> Refresh token value received when obtaining access token
<client_id> API client id as provided by Buildxact
<client_secret> API client secret/password as provided by Buildxact
<grant_type> "refresh_token"