Business Central API vs Web Services: What Is the Difference?

Business Central gives you several ways to expose data and operations to other systems: standard APIs, custom API pages, OData web services and SOAP. They look similar from a distance and behave differently in practice. This article explains what each one is, where they differ, and how to choose for a new integration.

The four options at a glance

• Standard APIs (v2.0): Microsoft-provided endpoints for common entities such as customers, items, sales orders and general ledger entries.
• Custom API pages and queries: API objects you write in AL to expose your own tables, fields and logic under your own publisher, group and version.
• OData web services: existing pages, queries or codeunits published as services under a service name.
• SOAP web services: the older protocol for pages and codeunits, now deprecated.

API pages: designed for integration

An API page is a page of type API. It is built for machine consumption: it has no UI, its fields are addressed by explicit names, and its URL includes a version. That is the important part. When you change the internals of your extension, the contract that consumers see stays stable until you deliberately publish a new version.

page 50140 "CE Item Stock API"
{
    PageType = API;
    APIPublisher = 'centralera';
    APIGroup = 'inventory';
    APIVersion = 'v1.0';
    EntityName = 'itemStock';
    EntitySetName = 'itemStocks';
    SourceTable = Item;
    DelayedInsert = true;
    ODataKeyFields = SystemId;
    Editable = false;

    layout
    {
        area(Content)
        {
            repeater(Group)
            {
                field(id; Rec.SystemId) { Caption = 'Id'; }
                field(number; Rec."No.") { Caption = 'Number'; }
                field(displayName; Rec.Description) { Caption = 'Display Name'; }
                field(inventory; Rec.Inventory) { Caption = 'Inventory'; }
            }
        }
    }
}

Consumers call it at a URL of this shape:

https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environment}/api/centralera/inventory/v1.0/companies({companyId})/itemStocks

API pages also support ETag-based concurrency, filtering and paging through OData query options, and webhook subscriptions for change notifications on supported entities. Microsoft's guidance is to prefer API pages and queries for integrations.

OData web services: publishing what already exists

A web service is created by publishing an object under a service name. Publish a page and it becomes available over OData at a URL such as:

https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environment}/ODataV4/Company('{companyName}')/{ServiceName}

Publishing a codeunit exposes its procedures marked with the [ServiceEnabled] attribute as OData unbound actions, which is how many teams trigger operations such as "release this order" from outside. The convenience is real, and so are the risks. Field names come from the page controls, so renaming a control can break consumers. And because a page is a UI object, its triggers and validation logic run as they would for a user, which may be more than you want in an integration and can be slower than an API page.

SOAP: plan your exit

SOAP was the original web service protocol. Microsoft's documentation now describes it as deprecated and points teams to OData or to API pages and queries. It also states that publishing Microsoft's own UI pages as SOAP endpoints will be removed in Business Central 2026 release wave 2 (version 29). Custom pages and codeunits are a separate case, so check the current position in Microsoft's SOAP documentation and the deprecated-features list. For any new work, do not choose SOAP; for existing SOAP consumers, put migration on the roadmap.

Side-by-side comparison

Authentication

In Business Central online, integrations authenticate with OAuth 2.0 through Microsoft Entra ID. Web service access keys, the old basic-authentication route, were deprecated in October 2022 and are not the way to build anything new. For service-to-service integrations, the usual pattern is an app registration with the client-credentials flow, requesting a token for the scope https://api.businesscentral.dynamics.com/.default, with the application registered inside Business Central and given a least-privilege permission set. On-premises deployments have their own authentication options.

Limits and reliability

Whichever interface you choose, design for the environment's limits. Business Central applies throttling to protect the service, returning HTTP 429 responses when a client sends too many requests, so consumers need retry logic with back-off. Read large data sets in pages rather than in one request, use filters to restrict them, and avoid chatty designs that make one call per record. Make writes idempotent, so a retry after a timeout cannot create a duplicate order.

Which should you use?

1. Need standard data (customers, items, orders) and Microsoft's standard fields cover it? Use the standard API v2.0.
2. Need custom fields, your own tables or shaped payloads? Build a custom API page. Use an API query for read-only joins.
3. Need to trigger a business operation? Use a bound action on an API page, or an unbound action through a codeunit web service.
4. Maintaining an existing consumer on a published page? Keep the OData web service for now, and plan a move to API pages.
5. Considering SOAP for a new project? Don't.

If you would like help designing or building any of this, see our Business Central API integration service, or read how to call external services from AL in HttpClient and JSON in AL.