How to Use APIs in Business Central

Business Central exposes data through OData v4 REST APIs. These APIs let external applications read and write BC data, customers, vendors, items, sales orders, and more, without direct database access. The same APIs power the Power Automate connector and the Edit in Excel add-in.

There are two types of API pages: standard API pages (published by Microsoft) and custom API pages (built with AL). This guide focuses on the standard APIs available in every Business Central environment.

Prerequisites

A Business Central environment (cloud or on-premises)
An Azure AD app registration with API permissions (for OAuth 2.0), or a BC user with a web service access key (for Basic Auth on on-premises)
A REST client such as Postman or curl for testing

Finding the Base URL and Available Endpoints

The base URL for Business Central APIs follows this pattern:

https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environment}/api/v2.0/

To find your company ID and list available companies, make a GET request to:

https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environment}/api/v2.0/companies

This returns a JSON array of companies in your tenant. Each company object includes an id field, which you use in all subsequent requests.

Once you have a company ID, you can access entity endpoints such as:

/api/v2.0/companies({companyId})/customers
/api/v2.0/companies({companyId})/vendors
/api/v2.0/companies({companyId})/items
/api/v2.0/companies({companyId})/salesOrders

Authenticating with OAuth 2.0

For Business Central cloud environments, all API calls require OAuth 2.0 bearer tokens. On-premises deployments support Basic Auth using a web service access key.

OAuth 2.0 (cloud):

Register an app in Azure Active Directory and grant it the Financials.ReadWrite.All API permission for Business Central.
Request a token from https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token using the client credentials or authorization code flow.
Include the token in every request as an Authorization: Bearer {token} header.

Basic Auth (on-premises only):

Use the format Authorization: Basic {base64(username:webServiceAccessKey)}. The web service access key is generated on the User Card in Business Central.

Making a GET Request

To retrieve a list of customers:

GET https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environment}/api/v2.0/companies({companyId})/customers
Authorization: Bearer {token}

A successful response returns HTTP 200 with a JSON body:

{
  "@odata.context": "...",
  "value": [
    {
      "id": "5d115c9c-44e3-ea11-bb43-000d3a298abb",
      "number": "C00010",
      "displayName": "Alpine Ski House",
      "email": "[email protected]",
      "currencyCode": "USD",
      "blocked": " "
    }
  ]
}

Filtering and Selecting Fields

OData query parameters let you control what data is returned.

Filter by field value:

/customers?$filter=currencyCode eq 'USD'
/customers?$filter=displayName eq 'Alpine Ski House'

Select specific fields:

/customers?$select=number,displayName,email

Combine filter and select:

/customers?$filter=blocked eq ' '&$select=number,displayName,currencyCode

Paginate results:

/customers?$top=50&$skip=50

Use $top and $skip to page through large result sets. The API returns a maximum of 100 records per page by default.

Creating Records with POST

To create a new customer, send a POST request with a JSON body:

POST /companies({companyId})/customers
Content-Type: application/json
Authorization: Bearer {token}

{
  "displayName": "Contoso Ltd",
  "email": "[email protected]",
  "currencyCode": "EUR"
}

A successful create returns HTTP 201 with the full created record, including the system-assigned id.

Updating Records with PATCH

To update an existing record, send a PATCH request to the entity URL including the record ID:

PATCH /companies({companyId})/customers({customerId})
Content-Type: application/json
If-Match: *

{
  "email": "[email protected]"
}

Only include the fields you want to change. The If-Match: * header is required to confirm you accept the update regardless of concurrent changes. For stricter concurrency control, use the @odata.etag value from the GET response instead of *.

Standard vs. Custom API Pages

Standard API pages are maintained by Microsoft and available in every BC environment without additional development. Custom API pages are built in AL and published by your development team or an ISV. They follow the same OData v4 conventions but use a different URL path based on the APIPublisher, APIGroup, and APIVersion properties defined in the AL page object.

If you need to expose data that is not covered by the standard APIs, such as custom tables or additional fields, a custom API page is the right approach.

If you need to expose pages or codeunits for SOAP-based integrations, see How to Use Web Services in Business Central.