Build Software API Guide

Introduction

The Build Software REST API provide secure access to business data through Azure API Management (APIM). All requests go through the APIM gateway, and every request must include both:

A Subscription Key (identifies your subscription and defines which products you can use).
A Bearer Token (OAuth2 authentication via Microsoft Entra ID).

This ensures that only authorized clients can connect to Build Software services.

1. Base URL

Each environment has its own Base URL.

https://apim-bs-apirelay-tst-01.azure-api.net/

Endpoints are appended to the base URL. Example:

https://apim-bs-apirelay-tst-01.azure-api.net/finance-api/odata/v1/PurchaseInvoices

2. Subscription Keys

A subscription key is required for every request:

Keys are centrally managed by Build Software.
If you need a key, contact Build Software Support.
Your key determines which produtcs you are allowed to access.

Header format:

Ocp-Apim-Subscription-Key: {your-key}

3. Authentication with OAuth2

All requests also require an OAuth2 Bearer Token obtained through Microsoft Entra ID:

Tokens are temporary and must be refreshed when expired.
This ensures that requests are tied to a valid user identity.

Header format:

Authorization: Bearer {access-token}

4. Required Headers

Header	Description	Required
Ocp-Apim-Subscription-Key	Identifies your subscription and API access	✅
Authorization	OAuth2 Bearer token (Microsoft Entra ID)	✅

5. Query Parameters (OData Support)

The APIs support OData query parameters for filtering, sorting, and shaping responses.

Parameter	Description	Example
$filter	Filter results by condition	$filter=InvoiceDate gt 2023-01-01
$select	Select specific fields	$select=InvoiceId,Supplier,Amount
$orderby	Sort results	$orderby=InvoiceDate desc
$top	Limit the number of results	$top=10
$skip	Skip results (pagination)	$skip=20
$count	Return total number of results	$count=true

Example:

GET /finance-api/odata/v1/PurchaseInvoices?$filter=InvoiceDate gt 2023-01-01&$top=10&$orderby=InvoiceDate desc

6. Example Requests

Finance API – Purchase Invoices

GET https://apim-bs-apirelay-tst-01.azure-api.net/finance-api/odata/v1/PurchaseInvoices?$top=5&$orderby=InvoiceDate desc

Headers:
    Ocp-Apim-Subscription-Key: 123456abcdef...
    Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGci...

General API – Sites

GET https://apim-bs-apirelay-tst-01.azure-api.net/general-api/odata/v1/sites

Headers:
    Ocp-Apim-Subscription-Key: 123456abcdef...
    Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGci...

7. Quickstart

Request your subscription key from Build Software Support.
Obtain a Bearer Token via Microsoft Entra ID login.
Add both headers to your request.
Send your first API call:

GET https://apim-bs-apirelay-dev-01.azure-api.net/finance-api/odata/v1/PurchaseInvoices?$top=1