Business Central API Integration: Complete Beginner Guide

Dynexal • Beginner to Intermediate • 14 min read

Business Central APIs make it possible to exchange ERP data with websites, mobile apps, e-commerce platforms, middleware and other business systems. This guide explains the API architecture, standard APIs, custom API pages, API queries, endpoints, authentication concepts, CRUD operations and practical testing.

What you will learn: REST APIs, standard API v2.0, custom API pages, API queries, endpoint structure, CRUD operations, Microsoft Entra authentication concepts, Postman testing, troubleshooting and integration best practices.

What is a Business Central API?

An API is an interface that allows an external application to communicate with Business Central over HTTP. Business Central provides built-in REST APIs and also lets AL developers create custom APIs using API pages and API queries. Microsoft describes the Business Central API stack as a preferred integration approach for REST-based integrations.

This makes APIs useful for scenarios such as synchronizing customers from a website, sending orders from an e-commerce platform, reading inventory into a mobile application, or connecting Business Central to an integration platform.

Microsoft Learn: API development overview

Standard APIs vs custom APIs

Business Central includes standard APIs for commonly used business entities. These can often be used without writing an AL API object. When the standard API does not expose the data or behavior required by your integration, you can create a custom API.

Standard API: use Microsoft's built-in endpoints when they provide the fields and operations you need.
Custom API page: use an AL API page when you need a custom read/write endpoint based on a table.
API query: use an API query for read-only data, especially when data needs to be combined from multiple sources.

Microsoft currently documents API pages as supporting read, create, update and delete operations, while API queries are read-only and can join data from multiple sources.

Business Central API endpoint structure

A Business Central Online API endpoint generally follows this structure:

https://api.businesscentral.dynamics.com/v2.0/{environment}/api/v2.0/{endpoint}

For a custom API, the route also contains your publisher, group and version:

https://api.businesscentral.dynamics.com/v2.0/{environment}/api/{publisher}/{group}/{version}/{endpoint}

For company-specific requests, the company can be represented in the endpoint, for example:

https://api.businesscentral.dynamics.com/v2.0/{environment}/api/v2.0/companies({companyId})/customers

Always use the endpoint format appropriate for your Business Central environment and API version. Microsoft documents the current endpoint structure in detail.

Microsoft Learn: API endpoint structure

Create a custom API page in AL

If your integration needs a custom read/write endpoint, an API page is a common AL solution. A minimal example looks like this:

page 50120 "Dynexal Customer API"
{
    PageType = API;
    Caption = 'Dynexal Customer API';

    APIPublisher = 'dynexal';
    APIGroup = 'integration';
    APIVersion = 'v1.0';

    EntityName = 'customer';
    EntitySetName = 'customers';

    SourceTable = Customer;
    DelayedInsert = true;
    ODataKeyFields = SystemId;

    layout
    {
        area(Content)
        {
            repeater(Group)
            {
                field(id; Rec.SystemId)
                {
                    Caption = 'Id';
                    Editable = false;
                }
                field(number; Rec."No.")
                {
                    Caption = 'Number';
                }
                field(name; Rec.Name)
                {
                    Caption = 'Name';
                }
                field(city; Rec.City)
                {
                    Caption = 'City';
                }
            }
        }
    }
}

The API metadata properties are important. APIPublisher, APIGroup and APIVersion determine the API route, while EntityName and EntitySetName determine the exposed resource names.

Microsoft Learn: API page type

API Page properties you should understand

PageType = API; identifies the object as an API page rather than a user-interface page.
APIPublisher identifies the publisher namespace used by your API route.
APIGroup groups related API endpoints.
APIVersion gives the API an explicit version such as v1.0.
EntityName defines the singular entity name.
EntitySetName defines the collection name.
ODataKeyFields identifies the field used as the OData key; SystemId is commonly used for API pages.
DelayedInsert is commonly used on API pages so records are inserted when the request is ready to commit.

API Page vs API Query

Choosing the right API object is important.

API Page	API Query
Supports read/write operations	Read-only
Usually exposes one source table	Can combine data from multiple sources
Useful for CRUD-style integrations	Useful for reporting and combined read models
Supports webhook scenarios	Designed for read access

Simple rule: if an external system needs to create or update Business Central records, start by evaluating an API page. If it only needs combined read-only data, an API query may be a better fit.

CRUD operations

CRUD means Create, Read, Update and Delete. API pages support these operations unless the corresponding permissions are restricted by the API object properties and application behavior.

GET: read a collection or a specific resource.
POST: create a new resource.
PATCH: update selected fields on an existing resource.
DELETE: remove a resource when deletion is allowed and appropriate.

A typical integration flow might be: external website sends a POST request to create an order, Business Central processes it, and the external system later uses GET requests to read the order status.

Testing a Business Central API with Postman

Postman is useful for learning and troubleshooting REST integrations. A basic GET request can be used to verify that an endpoint responds correctly.

GET https://api.businesscentral.dynamics.com/v2.0/{environment}/api/v2.0/companies({companyId})/customers

For a POST request, the request body depends on the fields exposed by the endpoint. For example:

{
  "name": "Dynexal Demo Customer",
  "city": "Noida"
}

In Postman, configure the request URL, HTTP method, authentication, headers and body. Start with a simple GET request before testing create or update operations.

Important: do not paste real production access tokens, client secrets or passwords into screenshots, blog posts, GitHub repositories or public examples.

Authentication concepts

Business Central Online integrations commonly use Microsoft Entra ID-based authentication. Your integration architecture determines how the application obtains an access token and which Business Central permissions the identity receives.

Think about authentication as two separate questions:

Who is calling? The identity is authenticated through the configured Microsoft Entra authentication flow.
What can it do? Business Central permissions determine which data and operations that identity can access.

For production integrations, use the authentication flow recommended for your application type and avoid embedding secrets in source code.

Common API errors

401 Unauthorized

The request is not authenticated correctly or the access token is missing, expired or invalid. Check the authentication configuration and token scope.

403 Forbidden

The identity is authenticated but does not have sufficient permissions for the requested resource or operation.

404 Not Found

Check the environment name, API route, company ID, endpoint name and API version. Custom APIs also require the correct publisher, group and version.

400 Bad Request

The request may contain invalid JSON, an invalid field name, an unsupported value or a missing required property.

429 Too Many Requests

Your integration may be sending requests too quickly. Design clients to handle throttling and retry responses appropriately instead of continuously retrying without delay.

API versioning

Do not treat an API URL as something that can never change. Version custom APIs deliberately. A version such as v1.0 gives you a stable contract while allowing a future v2.0 to introduce breaking changes.

Good integration practice: document your API contract, keep response fields stable, avoid unnecessary breaking changes and communicate version changes to consumers before migration.

Business Central API integration architecture

A real integration normally contains more than Business Central and an HTTP request. A common architecture looks like this:

Website / Mobile App / Shopify
            |
            v
     Integration Layer
            |
            v
   Business Central API
            |
            v
       AL Business Logic
            |
            v
     Business Central Data

The integration layer can be middleware, an Azure service, an e-commerce connector or another application. Keeping responsibilities separated makes the solution easier to monitor, secure and maintain.

Best practices for Business Central APIs

Prefer standard APIs when they already meet the business requirement.
Create custom APIs only when you need a custom contract or data model.
Keep API pages focused on integration data rather than user-interface concerns.
Use clear publisher, group, entity and version names.
Use SystemId appropriately as an integration identifier.
Validate data before performing important business operations.
Keep authentication secrets out of AL source code and public repositories.
Log integration failures with enough context to troubleshoot them without exposing sensitive data.
Handle throttling and transient failures with controlled retry logic.
Test GET requests first, then create and update operations with non-production data.

What should you learn next?

Codeunits in Business Central — move reusable business logic into dedicated AL codeunits.

AL Tables in Business Central — understand the data structures behind your APIs.

Page Extensions in Business Central — extend the Business Central user experience.

RDLC Reports in Business Central — learn the reporting side of Business Central development.

Creating List and Card Pages in AL — build the user interface for your Business Central data.

← Explore all Dynexal tutorials