Integrating with the Microsoft Dynamics Business Central API involves several clear steps. This process starts with making sure the environment is ready for API connections.

The first part of any integration journey is verifying that the right features are available and enabled. Without these initial settings, later steps will not work as expected.

This guide explains the technical steps for activating and preparing Business Central APIs for integration.

Enable Business Central APIs

Before starting any integration work, APIs in Microsoft Dynamics Business Central need activation. This is the foundation step.

Start by confirming that the Business Central license includes access rights for API usage. Navigate to Feature Management within Business Central to verify that API services are listed and available for activation.

Next, access the Business Central admin center. Within the admin center, locate the API Setup section. Find and click the "Integrate APIs" button. This activates the API endpoints and allows external applications to connect to Business Central.

Register an Azure App and Authenticate With OAuth 2.0

API access to Microsoft Dynamics Business Central uses OAuth 2.0 authentication through Microsoft Entra ID (formerly Azure Active Directory). This replaces older basic authentication methods.

Open the Azure portal and navigate to Entra ID to register a new application. Single-tenant registration restricts access to users in one organization, while multi-tenant registration allows users from multiple organizations to access the application.

In the app registration, add the "user_impersonation" permission for Dynamics 365 Business Central. Admin consent allows the application to use these permissions on behalf of users. An administrator completes this step by approving the requested permissions.

Create credentials for the app registration by generating either a client secret or certificate:

• Client secret: A password-like string that's easier to set up but less secure.
• Certificate: A cryptographic key pair that provides stronger security for production environments.

Use the OAuth 2.0 protocol to request an access token from Microsoft Entra ID. This token is included in API calls to authenticate requests. Access tokens expire after a set period and can be refreshed using a refresh token.

Understand the Base URL and Tenant Structure

Business Central API endpoints follow a specific structure that determines how applications connect to different environments. The endpoint structure uses URLs that reflect both the environment and tenant setup.

The standard API endpoint format for a single-tenant environment is:
https://api.businesscentral.dynamics.com/v2.0/<environment>/api/v2.0

In this URL, <environment> represents the specific Business Central environment, such as "Production" or "Sandbox". The environment name is case-sensitive and matches the label used in the Business Central admin center.

For multi-tenant setups, the endpoint includes the user domain name or tenant identifier:
https://api.businesscentral.dynamics.com/v2.0/<tenantdomain>/<environment>/api/v2.0

Business Central environments are typically divided into "Sandbox" (development and testing) and "Production" (live operations). Using the correct URL for each environment keeps test data and live data separate.

Required Roles and Permissions in Business Central

API access in Microsoft Dynamics Business Central depends on user roles and permissions. When using OAuth 2.0, the token received for authentication carries the same permissions as the user or application it represents.

Create dedicated service accounts in Business Central for API access. Assign permission sets such as "D365 AUTOMATION" or configure custom roles that match the required access level for integration tasks. These accounts provide clear control and tracking of which system processes interact with the API.

For application-only authentication, use a service principal - a security identity used by applications or services. Assign permissions to the service principal that align with the tasks the integration will perform. Service principals are commonly used to avoid relying on individual user accounts for automated API connections.

Perform CRUD Operations on Standard Entities

Business Central APIs support standard HTTP operations for working with data. These operations allow retrieval, creation, updating, and deletion of entity records using well-defined endpoints.

A GET request retrieves data from Business Central. To list all customers for a company, use:
GET /companies({companyId})/customers

The {companyId} value identifies the specific company. Include the Authorization: Bearer {access_token} header and set Accept: application/json to request a JSON response.

A POST request creates new records. Creating a sales order involves sending a request to:
POST /companies({companyId})/salesOrders

The request body contains a JSON payload specifying required fields such as customerId, orderDate, and order lines.

A PATCH request updates existing records with new information. To update a customer:
PATCH /companies({companyId})/customers({customerId})

Include only the fields that require changes in the JSON payload. Business Central uses ETags to handle concurrency through the If-Match header.

A DELETE request removes records:
DELETE /companies({companyId})/customers({customerId})

Deleting records may be restricted by referential integrity rules. If a record links to other entities, deletion may fail or trigger cascading deletions.

Use Query Parameters for Filtering and Paging

OData query parameters control which data returns from the Business Central API. These parameters are added to the URL and help retrieve specific subsets of data.

The $filter parameter narrows down results by applying conditions to fields:

/customers?$filter=displayName eq 'Contoso'

The $select parameter specifies which fields to return:

/customers?$select=id,displayName,email

The $orderby parameter sorts results by one or more fields:

/customers?$orderby=displayName asc

The $top parameter controls how many records return in one response:

/customers?$top=10

The $skip parameter skips a certain number of records:

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

Using $top and $skip together enables paging through large datasets.

Handle Pagination, Rate Limits, and Errors

Business Central APIs organize data in pages, apply limits on request frequency, and provide structured error messages.

When a dataset is too large for one response, Business Central sends a subset of results and includes an @odata.nextLink property. This property contains a URL for the next set of results. Applications can follow each nextLink value until the response no longer contains one.

Business Central APIs apply rate limits that control request frequency. When limits are reached, the API returns a 429 Too Many Requests status code. Integrations can detect this status code and wait before retrying. Exponential backoff increases wait time after each repeated limit.

When Business Central APIs encounter errors, they respond with structured JSON objects containing:

• HTTP status code: Such as 400, 401, 403, or 500.
• Error object: Contains a code and message for specific problem identification.
• Additional details: Business Central-specific error information for troubleshooting.

Create and Publish Custom APIs With AL

Business Central allows creation of custom APIs to handle scenarios not covered by standard endpoints. This involves using AL (Application Language), the programming language for Microsoft Dynamics 365 Business Central.

Standard API pages are available in the ALAppExtensions repository on GitHub. These source files can be downloaded and used as starting points for creating new custom APIs. Templates help maintain consistency with existing API conventions.

Additional fields can be added to copied API pages to support new requirements. When adding custom fields, follow versioning guidelines to avoid breaking changes in the API for consumers.

Custom APIs are published as AL extensions. Initial deployment occurs in a Sandbox environment, separate from production. Testing in Sandbox allows validation of functionality and detection of issues before affecting live data.

After successful testing in Sandbox, the extension can move to production. Change management and rollback procedures help maintain stability in live operations.

Scale Integrations Across Multiple Tenants

Managing integrations for multiple Business Central tenants involves addressing separate authentication, data isolation, and event handling for each environment.

Token caching involves storing authentication tokens for each tenant in secure storage. When an API request is made, the cached token is checked for validity before performing authentication again. Token caches are indexed by tenant identifiers to prevent cross-tenant access.

Webhook fan-out delivers event notifications to multiple tenant endpoints when relevant changes occur. When Business Central sends a webhook event, the system identifies affected tenants and routes events to each configured destination. Distributed environments may use message queues to process events asynchronously.

Partnering With Microsoft and Listing on AppSource

After completing your integration, you can extend its reach by publishing on Microsoft AppSource, the marketplace for Business Central and other Dynamics 365 solutions.

Listing on AppSource provides:

• Visibility to Business Central customers actively searching for integrations.
• Validation through Microsoft’s certification process, which reviews security, compliance, and performance.
• Deployment directly from AppSource into customer environments.

Steps to Publish

1. Enroll in the Microsoft Partner Center.
2. Package your solution as a Business Central extension (.app file).
3. Submit your listing with documentation and assets.
4. Complete Microsoft’s certification and validation process.

Maintaining your listing requires keeping the extension compatible with the latest Business Central updates and providing clear documentation for customers.

Direct Integration vs Unified API Platforms Like Apideck

Direct integration involves building and maintaining custom connections to the Business Central API. This approach allows full control over data flow, feature usage, and error management. Developers can tailor every aspect of the integration to match specific business requirements.

However, direct calls require ongoing responsibilities:

• Authentication management: Handling OAuth flows and token refresh logic.
• API change tracking: Keeping up with Microsoft's updates and deprecations.
• Error handling: Building robust retry and fallback mechanisms.
• Multiple system complexity: Repeating similar work for each additional ERP system.

A unified API platform acts as a single access point for connecting to multiple systems like Business Central and other ERPs. This platform provides one authentication process and standardized data format, so developers interact with a consistent API regardless of the connected system.

Using a unified layer reduces effort when adding new integrations. Maintenance tasks such as handling authentication, normalizing data, and adapting to upstream changes are managed centrally by the platform.

Next Steps for Faster Integrations

After setting up authentication, permissions, and endpoint configurations, the next phase involves choosing an integration approach. Teams can write direct code for each API connection or use a unified solution to manage multiple systems.

Apideck offers an Accounting API that connects to Microsoft Dynamics Business Central and other ERP systems through a single interface. This API uses pre-built connectors and normalized data models to handle integration requirements.

Get Started With Apideck to accelerate your Business Central integration timeline.

FAQs About Microsoft Dynamics Business Central API Integration

How do Business Central sandbox rate limits compare to production environments?

Sandbox environments have lower rate limits compared to production environments. Microsoft uses different throttling policies in sandbox instances to promote good testing practices and prevent overuse of shared resources.

Can the Business Central REST API be called without user interaction?

The API can be called without user interaction by using service principal authentication with the client credentials flow. This setup allows automated, server-to-server integrations that don't depend on a user being present.

What happens when custom fields change after Business Central API extension deployment?

Changing custom fields after an API extension deployment requires updating and redeploying the extension. If integrations rely on fields that are modified or removed, those integrations may break, requiring careful change management.

How can OAuth 2.0 client secrets be rotated without causing Dynamics 365 integration downtime?

Dual-secret rotation involves creating a new client secret before the current one expires. Integration code is updated to use the new secret, and the old secret is deleted only after confirming the new one works, allowing authentication to continue without interruption.