What we do
Tools
Industries
Department
How we workLet's talk →
Home/Dynamics 365/Calling the Business Central API v2.0
Dynamics 365 Business Central

Your First Business Central API Call, and What Breaks After It

The partner who set up Business Central has moved on, and the web store's orders need to land in it. Microsoft's answer is spread across a dozen Learn pages: endpoints in one, Entra in another, limits and webhooks somewhere else. The risk isn't the first call. It's the webhook subscription that lapses after three days, so orders stop syncing and nobody notices until a customer asks where theirs went.

Business Central API v2.0 in four lines

Base URL (online): https://api.businesscentral.dynamics.com/v2.0/{tenant}/{environment}/api/v2.0, where the tenant is your tenant ID or domain and the environment is its name, such as production or sandbox.

Auth: a Microsoft Entra ID bearer token. For unattended jobs, use the client credentials flow with the scope https://api.businesscentral.dynamics.com/.default.

First call: GET .../companies. Every business entity sits under one company, so the next call looks like .../companies({id})/customers.

Change notices: POST .../subscriptions with a notificationUrl and a resource. Your endpoint has to echo back a validationToken, and the subscription expires after three days unless you renew it.

Service-to-service access to Business Central, set up once

This is Microsoft's route for integrations that run without anyone signed in. Delegated sign-in can require MFA, which stops an overnight job cold.

  1. 1

    Register an app in Microsoft Entra

    Entra admin center App registrations New registration

    Name it for the integration, choose single-tenant unless you're building for many customers, and copy the Application (client) ID from the Overview page.

  2. 2

    Give it a client secret

    Certificates & secrets New client secret

    Pick a duration and copy the value straight away. Entra never shows it again, so it goes into your secret store, not a config file.

    Watch for: the expiry date. A secret that lapses stops the integration with an auth error, so put the renewal in someone's calendar.

  3. 3

    Grant the Business Central permission

    API permissions Add a permission Dynamics 365 Business Central Application permissions

    Tick API.ReadWrite.All (add Automation.ReadWrite.All only if you'll use the automation APIs), then grant admin consent for the tenant.

  4. 4

    Add the app inside Business Central

    Search for Microsoft Entra Applications, choose New, paste the client ID, set State to Enabled, and assign permission sets that cover only the objects the integration touches.

    Watch for: the SUPER permission set. Business Central won't let you assign it to an application, which is Microsoft nudging you towards least privilege.

  5. 5

    Get a token and call companies

    POST to https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token with grant_type=client_credentials, the client ID, the secret and the scope. Send the token as Authorization: Bearer ... on GET .../companies, keep the company id, and build every other path on it.

Business Central API limits, and what you get back when you hit one

Online limits, applied per user. An application's service principal counts as a user, so one integration identity carries all of its own traffic.

Limit Value What it looks like
Requests in a 5-minute sliding window 6,000 HTTP 429 Too Many Requests. Back off and retry; Microsoft treats a retry with a cool-off as expected behavior.
Requests processed at once 5 Extra requests queue. A request left waiting 8 minutes returns 503.
Requests in flight, including queued 100 (95 queued) Anything beyond that gets a 429 straight away.
Entities returned by one request 20,000 HTTP 413. Page with $top and $skip or follow the next link.
Operations in one $batch 100 Split bigger loads across several batches.
Time allowed for one request 8 minutes HTTP 408, and the session is canceled.
Webhook subscriptions per environment 200 Subscribe to the resources you need, not every entity just in case.

Business Central API or the Dataverse Web API

Microsoft sells both under the Dynamics 365 label. They aren't the same API, and code for one won't run against the other.

Business Central

Finance, sales orders, inventory for SMB

  • API v2.0 pages built in AL, under api.businesscentral.dynamics.com.
  • Standard entities can't be extended with extra fields. You copy the AL for that API and publish a custom API page at api/{publisher}/{group}/{version}.
  • On-premises installs use a username and web service access key instead of Entra.
Dataverse

Sales, Customer Service, Field Service

  • An OData v4 Web API at your organization's URL, under /api/data/.
  • Custom tables and columns appear in the API without extra work.
  • Older CRM integrations on the SOAP Organization Service (the 2011 endpoint) are deprecated and belong on the Web API.

If the data is ledgers, items or sales documents, it's Business Central. If it's leads, cases or opportunities, it's Dataverse. The Dynamics 365 integrations page maps Finance and Operations too.

Business Central integrations that pass testing and fail in week two

Webhook subscriptions left to expire

How you'll know: Notifications stop about three days after go-live.

Fix: Renew each subscription with a PATCH before its expirationDateTime. Renewal repeats the handshake, so your endpoint has to answer the validationToken every time, not just on day one.

A bulk change arrives as one notice

How you'll know: A price update touched 4,000 items and your system got a single message with no item IDs.

Fix: Business Central waits 30 seconds after a change, and if more than 1,000 records changed it sends one collection notice with a filter. Read it as "re-query with this filter". Power Automate flows don't fire for these at all.

Answering a notification with the wrong error

How you'll know: One bad deployment, and the subscription is gone.

Fix: Business Central only retries (for up to 36 hours) when your endpoint returns 408, 429 or a 5xx. Any other failure code deletes the subscription, so return a 503 while you're down and handle real errors after you've acknowledged the call.

A field you need isn't on the standard API

How you'll know: The customer's custom credit field is in the UI and missing from /customers.

Fix: Standard API pages can't be extended. Publish a custom API page in an extension, under your own publisher and group, with exactly the fields the integration needs.

Old authentication carried over from on-premises

How you'll know: A move to Business Central online, and every call returns 401.

Fix: Online only accepts Entra ID tokens. Replace the username and web service access key with the app registration above.

Business Central API questions

Does Dynamics 365 have a REST API?

More than one. Business Central has its own REST API (v2.0 now), and the customer engagement apps such as Sales and Customer Service use the Dataverse Web API, built on OData v4. Finance and Operations exposes data entities over OData. Which you need depends on where the data lives.

Does Business Central have its own API, separate from Dynamics 365 CRM?

Yes. Its API pages are written in AL and served from api.businesscentral.dynamics.com, with their own versioning and permissions inside Business Central. The CRM apps sit on Dataverse with a different URL, schema and security model, so an integration written for one needs rework for the other.

Do I need a developer to use the Dynamics 365 API with Business Central?

To read a few records into a script, a technical admin can follow Microsoft's samples. For production work, yes: the Entra setup, token handling, paging, retries on 429s and webhook renewal all have to be built and watched. n-frames writes those pieces and keeps them running for Business Central clients.

Is the old Dynamics CRM web services API still supported?

The SOAP Organization Service that older Dynamics CRM integrations call (the 2011 endpoint) is deprecated, and Microsoft plans to switch it off for client apps that don't use its current service clients. Anything still pointed at it should be rebuilt on the Dataverse Web API before it fails on its own schedule.

Which Business Central entities support webhooks?

Most of the common ones, including customers, vendors, items, sales orders, sales and purchase invoices, journals and G/L entries. Ask your environment directly with the webhookSupportedResources call. Custom API pages are webhook-enabled too, unless they're built on a temporary table, a system table, a composite key or an API query.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.