Microsoft DynamicsFree generatorPDF, Excel, Word exportMicrosoft Dynamics 365 Business Central

Business Central API v2.0 URL Builder

Most Business Central integration errors come from a wrong URL: the company name used instead of the company GUID, a missing environment segment, or a custom API called with the standard path. This builder assembles the full set of calls for a SaaS tenant or an on-premises server so you can paste them into Postman, curl or your integration code.

Fill in

Deployment

Entra tenant ID (SaaS)

Directory (tenant) ID from Microsoft Entra ID.

Environment name (SaaS)

Server and port (on-prem)

Server instance (on-prem)

Company ID (GUID)

Get it from GET /companies. It is a GUID, not the company name.

Standard API entity

$select fields

$filter expression

OData syntax, for example status eq 'Open'.

$top

App registration client ID

Generated code

Download:

1. Discover the company ID

SaaS:
GET https://api.businesscentral.dynamics.com/v2.0/00000000-0000-0000-0000-000000000000/Production/api/v2.0/companies

On-premises:
GET http://bcserver:7048/BC/api/v2.0/companies

2. Entity request with OData options

SaaS:
GET https://api.businesscentral.dynamics.com/v2.0/00000000-0000-0000-0000-000000000000/Production/api/v2.0/companies(11111111-2222-3333-4444-555555555555)/salesInvoices?$select=number,customerNumber,invoiceDate,totalAmountIncludingTax&$filter=invoiceDate ge 2026-01-01&$top=50

On-premises:
GET http://bcserver:7048/BC/api/v2.0/companies(11111111-2222-3333-4444-555555555555)/salesInvoices?$select=number,customerNumber,invoiceDate,totalAmountIncludingTax&$filter=invoiceDate ge 2026-01-01&$top=50

Selected deployment: SaaS
Headers:
Authorization: Bearer <access token>
Accept: application/json

3. Token request (SaaS, client credentials)

POST https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=99999999-8888-7777-6666-555555555555&client_secret=<secret>&scope=https://api.businesscentral.dynamics.com/.default

4. curl test (replace the token)

curl -H "Authorization: Bearer <access token>" -H "Accept: application/json" "https://api.businesscentral.dynamics.com/v2.0/00000000-0000-0000-0000-000000000000/Production/api/v2.0/companies(11111111-2222-3333-4444-555555555555)/salesInvoices?$top=50"

Standard API v2.0 entity names are camelCase. Custom APIs use /api/{publisher}/{group}/{version}/companies(id)/{entitySet} instead. For client credentials the Entra app must also be registered in Business Central (Microsoft Entra Applications page) with permission sets. Verify field names against your BC version's API reference before production use.

Want Business Central data queryable in plain language?

Optional: a short call on connecting BC to a private natural-language layer without moving data out.

Optional. The tool and every export work without this. No spam.

How to use the builder

Choose SaaS or on-premises, enter your tenant ID and environment name (or server, port and instance), then paste the company GUID. Pick the entity and set $select, $filter and $top. The first block lists companies so you can find the GUID; the second is the real data call; the third requests an OAuth token with the client credentials flow; the fourth is a one-line curl test you can run from a terminal.

SaaS host is api.businesscentral.dynamics.com with the tenant and environment in the path
On-premises uses your server, the API port (7048 by default) and the instance name
Always call /companies first to get the GUID

How the API v2.0 path is structured

The standard API lives under /api/v2.0, then companies({id}), then an entity set such as customers or salesInvoices. Query options follow OData v4: $select trims columns, $filter restricts rows, $top limits page size, $expand pulls related lines (for example salesInvoiceLines), and $orderby sorts. Custom APIs published from AL extensions use the publisher, group and version path instead and are not under api/v2.0.

Authentication notes

SaaS integrations should use OAuth 2.0 with a Microsoft Entra app registration. The scope for client credentials is https://api.businesscentral.dynamics.com/.default. After the token works, the same app must be added in Business Central on the Microsoft Entra Applications page and given permission sets, otherwise you receive 401 or 403 even with a valid token. On-premises installations can use Windows or NavUserPassword authentication depending on the server configuration.

Common mistakes

Page size is capped by the server, so large tables must be read by following the @odata.nextLink value rather than assuming $top returns everything. Writes need the If-Match header with the record's ETag for PATCH and DELETE. Filtering on non-indexed fields over big tables is slow, and web service limits throttle bursts with HTTP 429, so retry with backoff.

Using the company display name instead of the GUID
Forgetting If-Match on PATCH
Ignoring @odata.nextLink paging
Not registering the Entra app inside Business Central

Frequently Asked Questions

What is the base URL for the Business Central API v2.0?

For SaaS it is https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environmentName}/api/v2.0. Then add companies({companyId}) and the entity set. On-premises it is http://server:port/instance/api/v2.0.

Where do I find the company ID?

Call GET .../api/v2.0/companies. The response lists each company with its id GUID and name. Use the id in companies({id}) for every later call.

Why do I get 401 with a valid token?

In SaaS the Entra application must also exist in Business Central on the Microsoft Entra Applications page, be set to Enabled, and have permission sets assigned. A token alone is not enough.

Can I use the same URL for custom APIs?

No. Custom API pages use /api/{publisher}/{group}/{version}/companies({id})/{entitySet}, based on the APIPublisher, APIGroup and APIVersion properties in the AL page object.

If you are building an integration or want to ask Business Central questions in plain language, Netray can review the design and connect it to your data, on-premises if needed.

Talk to an Expert Explore More Free Tools

Related Tools

Microsoft Dynamics

More Microsoft Dynamics tools

See all

Back to All Tools