# Business Central API v2.0 URL Builder

> Source: https://netray.co/tools/business-central-api-v2-url-builder
> Publisher: Netray (netray.co), AI and integration engineering for ERP and manufacturing systems.
> Section: Free Tools

## Short answer

Generate correct Business Central API v2.0 endpoints, OData query strings, the OAuth token request and a test call for SaaS or on-premises.

## Category

microsoft-dynamics

## Erp

Microsoft Dynamics 365 Business Central

## Audience

- BC developer
- BC partner consultant
- Integration engineer

## Tool

**Kind:** template

**Output:** code

**Language:** http

**Fields:**

#### Deployment

**Key:** env_type

**Type:** select

**Options:**

- SaaS
- On-premises

**Default:** SaaS

#### Entra tenant ID (SaaS)

**Key:** tenant

**Type:** text

**Default:** 00000000-0000-0000-0000-000000000000

**Help:** Directory (tenant) ID from Microsoft Entra ID.

#### Environment name (SaaS)

**Key:** environment

**Type:** text

**Default:** Production

#### Server and port (on-prem)

**Key:** server

**Type:** text

**Default:** bcserver:7048

#### Server instance (on-prem)

**Key:** instance

**Type:** text

**Default:** BC

#### Company ID (GUID)

**Key:** company_id

**Type:** text

**Default:** 11111111-2222-3333-4444-555555555555

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

#### Standard API entity

**Key:** entity

**Type:** select

**Options:**

- customers
- vendors
- items
- salesOrders
- salesInvoices
- purchaseInvoices
- glAccounts
- generalLedgerEntries

**Default:** salesInvoices

#### $select fields

**Key:** select

**Type:** text

**Default:** number,customerNumber,invoiceDate,totalAmountIncludingTax

#### $filter expression

**Key:** filter

**Type:** text

**Default:** invoiceDate ge 2026-01-01

**Help:** OData syntax, for example status eq 'Open'.

#### $top

**Key:** top

**Type:** number

**Default:** 50

#### App registration client ID

**Key:** client_id

**Type:** text

**Default:** 99999999-8888-7777-6666-555555555555

**Blocks:**

#### 1. Discover the company ID

**Body:** SaaS:
GET https://api.businesscentral.dynamics.com/v2.0/{{tenant}}/{{environment}}/api/v2.0/companies

On-premises:
GET http://{{server}}/{{instance}}/api/v2.0/companies

#### 2. Entity request with OData options

**Body:** SaaS:
GET https://api.businesscentral.dynamics.com/v2.0/{{tenant}}/{{environment}}/api/v2.0/companies({{company_id}})/{{entity}}?$select={{select}}&$filter={{filter}}&$top={{top}}

On-premises:
GET http://{{server}}/{{instance}}/api/v2.0/companies({{company_id}})/{{entity}}?$select={{select}}&$filter={{filter}}&$top={{top}}

Selected deployment: {{env_type}}
Headers:
Authorization: Bearer <access token>
Accept: application/json

#### 3. Token request (SaaS, client credentials)

**Body:** POST https://login.microsoftonline.com/{{tenant}}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={{client_id}}&client_secret=<secret>&scope=https://api.businesscentral.dynamics.com/.default

#### 4. curl test (replace the token)

**Body:** curl -H "Authorization: Bearer <access token>" -H "Accept: application/json" "https://api.businesscentral.dynamics.com/v2.0/{{tenant}}/{{environment}}/api/v2.0/companies({{company_id}})/{{entity}}?$top={{top}}"

**Notes:** 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.

## Content

**Intro:** 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.

**Sections:**

#### How to use the builder

**Body:** 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.

**Bullets:**

- 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

**Body:** 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

**Body:** 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

**Body:** 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.

**Bullets:**

- 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

**Cta:** 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.

**Faq:**

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

**Answer:** 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?

**Answer:** 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?

**Answer:** 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?

**Answer:** 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.

## Search terms

business central api v2.0 url, business central odata url builder, business central rest api example, dynamics 365 business central api endpoint, business central api companies id, business central api filter query, business central oauth token request, business central on-premises api url

---
Talk to an engineer: https://netray.co/contact?intent=erp_ai | Machine catalog: https://netray.co/agent/catalog.json