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
Directory (tenant) ID from Microsoft Entra ID.
Get it from GET /companies. It is a GUID, not the company name.
OData syntax, for example status eq 'Open'.
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.
Related Tools
Business Central Configuration Package Worksheet
Plan the tables, load sequence and expected error counts for Business Central RapidStart configuration packages before you import.
Developer ToolsBusiness Central AL Extension Skeleton Generator
Fill in publisher, prefix and ID range to get app.json, a table extension, a page extension, an event subscriber codeunit and a permission set.
Microsoft DynamicsBusiness Central Permission Set Design Worksheet
Map roles to objects and permission levels before you build permission sets, and flag segregation of duties risks early.
More Microsoft Dynamics tools
See all- Business Central Year-End Close Checklist
- Business Central Posting Groups Setup Worksheet
- Business Central Data Migration Field Mapping Worksheet
- Business Central Chart of Accounts Mapping Worksheet
- Business Central Implementation Statement of Work Template
- Business Central Functional Design Document Template
- Business Central User Acceptance Test Script Template
- Business Central Go-Live Cutover Plan Template
- Business Central License Cost Calculator
New to Microsoft Dynamics NAV and Business Central on-prem? Start with the Microsoft Dynamics NAV and Business Central on-prem guide and toolkit.
Keep exploring
Free tools
- D365 F&O OData URL BuilderFill in your environment, entity and query options to get a correctly formed D365 F&O OData request and a sample OAuth token call.
- Business Central On-Prem Private AI Layer Blueprint GeneratorDescribe your Business Central on-prem setup and get an architecture plan for a private AI assistant built on API v2.0 and a local model.
- D365 Finance and Operations OData URL and Token Request BuilderGenerate the OData request and OAuth token call to read data entities from D365 F&O during an AX migration or validation.
ERP fixes and how-tos
- Adding a Private AI Layer to Business Central On-PremisesAdd AI to Business Central on-prem without cloud: API v2.0, custom API pages, SQL replica, retrieval, local LLM, BC permission sets, approved write-back.
- Calling and extending the Business Central API v2.0Business Central API v2.0 explained: the endpoint URL, Azure AD app registration and OAuth 2.0 token, calling standard entities, and custom API pages in AL.
- Upgrade to Business Central 25: How to Update SaaS and On-PremisesHow to upgrade to Business Central 25 (2024 release wave 2): SaaS update from the admin center, on-premises upgrade steps, extension checks and a test plan.
AI on your ERP
- AI for Business Central manufacturing operations, beyond CopilotAI for Business Central manufacturing beyond Copilot: grounded answers on production orders, routings, and capacity via APIs v2.0, on-prem capable.
- AI for Dynamics 365 Business Central, on-premises or SaaS, beyond CopilotAI for Business Central beyond Copilot: grounded question answering over BC's data via OData and APIs, for on-premises and SaaS tenants alike.
Integrations
- How to add AI agents to Dynamics 365 Business CentralHow to add AI agents to Dynamics 365 Business Central: API v2.0 and custom API pages as the tool layer, approval gates, SaaS vs on-prem, and build options.
- How to add WhatsApp to Microsoft Dynamics 365 Business CentralHow to connect WhatsApp to Dynamics 365 Business Central: API v2.0 or custom API pages, webhooks, template messages, and two-way replies that post back safely.
Software
- Microsoft Dynamics 365 Business CentralDynamics 365 Business Central explained for manufacturers: modules, APIs, AL extensions, deployment, strengths, limits and alternatives for small and mid-size firms.
- Microsoft Dynamics 365 Finance and Supply ChainDynamics 365 Finance and Supply Chain Management explained for manufacturers: modules, data entities, OData, deployment, strengths, limits and alternatives.