BuildOn Technologies is a software product and services company that serves the needs of the homebuilder and construction industries. If you are one of our clients, you have lots of data, processes and systems that need to work together. This site has all the information on how BuildOn Technologies’ systems can work with your systems.
We use API Keys to authenticate systems that call our APIs. API Keys are alphanumeric tokens that are used to identify your company/system to our API. They are used to restrict data access and should be kept secret. API Keys are only valid for the Stack for which they are issued. If there is an issue we can generate a new API Key for you.
The API Key needs to be passed with any request that is made to any of the BuildOn APIs. It can be passed in the x-api-key via a header or query parameter.
BuildOn architectually separates customer data and execution environments into separate “Stacks”. Each of these stacks has its own databases and is deployed to its own servers.
Why does it matter?
Each stack has a its own dedicated set of APIs so in order to access or update your data you will need to know in which stack your data resides. API Keys are only valid for the stack for which they are issued.
Which stack do we use?
The BuildOn Stack is the default stack. If you are a customer of BuildOn most likely you will use the BuildOn Stack. We have setup custom stacks for several of our customers that are instillation companies. If you are one of these installation companies or one of their customers you will need to use their dedicated stack.
How are these stacks used?
When accessing BuildOn’s APIs, one of the segments of the URL will be the name of the stack. In our OpenAPI Documentation, you can select the different stacks. This does not change the documentation but it does allow you to connect to the correct stack via the “Try it out” buttons if you Authorize with your API Key.
Have Questions?
If you have questions about Stacks or anything else integration related, don’t hesitate to contact us.
Tenants are another way we segregate customer data within our stacks. Homebuilder’s data is typically segregated by city or geographic region into tenants. You will need the id of the tenant you want manipulate for most actions you want to perform with our APIs.
How do I find my Tenant Ids?
The VDS Integration API allows you to access your tenant information.
The /tenants endpoint returns a list of all tenants that have been associated with you API Key. The /tenants/{tenantid} endpoint will let you see meta-data about individual tenants.
Webhooks are a way to subscribe to system events so you can be notified automatically when they occur. For instance, you can subscribe to the SessionCompletedEvent in the BuildOn Business Events API and whenever a session is completed in your design center a message will be sent to an API that you control so you can pull session data and perform whatever business actions need to be done in your system.
The OpenAPI documentation can be found here: Business Events API. This is the full documentation including all accepted objects. You can even make calls to our services provided that you have an API Key.
This article will give you a brief overview of how this API can be utilized.
Subscribing
In order to receive events, you need to create a subscription. You can see all the events that we currently support by calling the events endpoint.
The full results can be seen below. Currently, we only publish the SessionCompletedEvent, but more will be added in the future.
{
"data": [
{
"id": "40d18e4f-6c49-4057-a8c0-dab14686141c",
"name": "SessionCompletedEvent",
"description": "Event that is fired when a session is completed in Veo Design Studio." }
]
}
Each event has an id, a name and a description. The description provides details of when the event will be triggered. The id is the value you will use to reference an event. The name is a human readable value for convenience.
The listing of events can be referenced without authentication. All other calls to the Business Events API require an API Key. You will also need your TenantId.
To create a subscription, you will POST a message to the subscriptions endpoint. This can be done via a tool like Postman or through our API Documentation.
You will need to supply the tenantId of the tenant that you want to subscribe to.
The eventId is the GUID id of the event that you want to receive notification for.
The url is the url of the API where you want to receive the notification. This should be an API that you have control of.
The isActive is optional. This flag lets you disable a subscription without deleting it. Any subscription with isActive set to false will not send out notifications.
The secret variable is optional also. It is used to cryptographically ensure that a message you receive is valid and comes from BuildOn. This will be elaborated on below.
To subscribe to the SessionCompletedEvent you can send the following message:
The organizationId is the organization the completed session is for. The sessionId is the id of the completed session. With these values, information about a completed session can be retrieved from the VDS Integration API.
For convenience, the sessionSelections link is provided on the links object. A GET call to the sessionSelections url will return all the selections that were selected during the completed session provided that you include your API Key with the call. For more information on sessions and session selections, see the VDS Integration API documentation.
Secret
The secret is used to verify cryptographically that only BuildOn is sending messages and that the messages have not been tampered with.
Your secret should be stored securely and should not be guessable.
When a webhook notification is sent and secret has been populated, a hash based on the payload and the secret is created and sent along with the payload in the x-signature-256 header. You can verify that the source and the payload are valid by computing your own hash and comparing it to the signature sent.
using System.Net.Http.Json;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
// This is for example only. This value should be stored securely.conststring _secret = "some secret that no one else knows";
publicbool VerifySignature(string payload, string signature)
{
string expectedSignature = GenerateSignature(_secret, payload);
return signature == expectedSignature;
}
privatestaticstring GenerateSignature(string secret, string payload)
{
var encoding = new UTF8Encoding();
byte[] keyBytes = encoding.GetBytes(secret);
byte[] payloadBytes = encoding.GetBytes(payload);
using var hasher = new HMACSHA256(keyBytes);
byte[] hashBytes = hasher.ComputeHash(payloadBytes);
return$"sha256={Convert.ToHexStringLower(hashBytes)";
}
Have Questions?
If you have questions about Webhooks or anything else integration related, don’t hesitate to contact us.
A token that is used to Authenticate and Identify an application or a system. It is normally sent in the header of an API call.
Integration
The process of bringing together sub-systems and making sure they function together as a system.
Estimated Options
See Measurable Options
Measurable Options
Options that are typically billed by footage. Flooring, Tiling or Countertops for example. They tend to have other associated options like underlayment or grout.
Non-Estimated Options:
See Non-Measurable Options
Non-Measurable Options
Options that are typically billed by count. Refrigerators are an example of these options.
Secret
A token or phrase used to cryptographically prove the authenticity of a message.
Session
A discrete container for the selections that a Designer or Homebuyer makes.
Session Selections
Detailed information about the Selections made in a Session by the Designer or Homebuyer. This information includes Measurable and Non-Measurable Option Selections. For Measurable Selections, it includes Bill of Materials information.
Stack
An architecural segmentation of customers data. Data lives on separate server instances.
Tenant
A logical segmentation of customers data. Data is separated by security policies.
VDS
A common acronym for VEO Design Studio.
Veo Design Studio
BuildOn’s Premium Home Building Software. This software is used by Homebuyers, Home Builders and Sales Counselors to handle all options data, selections, and pricing. More infomation can be found here.
Webhook
A way of for the consumer of an API to subscribe to system events so they can receive real-time, automated data via HTTP.