Business Central Custom API in AL: Upgrade-Safe Patterns
Versioned API pages with SystemId keys, OAuth, retry-safe consumers and an update checklist, checked against 2026 release wave 2.

On this page
A Business Central custom API is an AL page or query with its type set to API, published under your own APIPublisher, APIGroup and APIVersion route. Build one only when the standard API v2.0 cannot serve the integration, key it on SystemId, keep business logic in codeunits, and treat the route and fields as a versioned contract that consumers depend on.
This guide is for AL developers and integration owners who publish or inherit custom endpoints. Microsoft guidance was checked on 2026-11-18 against Business Central 2026 release wave 2 (version 29).
Review your integration environment. Book the free BC Environment Snapshot: one hour on a screen share with a Business Central consultant, then a written summary of your environment within five business days.
Microsoft recommends REST APIs for new Business Central integrations. Standard APIs cover many common entities, while AL API pages and API queries let you publish a purpose-built contract when the standard surface is not enough. That distinction matters: a user-interface page is optimized for people, while an API page is designed for predictable machine-to-machine access.
Start by proving that a Business Central custom API is necessary
Before writing AL, check the standard Business Central API v2.0 catalog. A standard endpoint reduces custom code and gives the consumer a Microsoft-owned contract. Create a custom endpoint when the integration needs a business-specific projection, an entity that is not exposed, or behavior that cannot be represented safely through the standard surface.
Do not copy a standard API merely to rename fields. Microsoft notes that standard API pages cannot currently be extended with additional fields; when extra fields are required, a separate custom API is the supported route. Keep that custom contract narrow instead of reproducing an entire card page. For read-only data that joins tables, consider an API query.
Integrations that call Microsoft UI pages over SOAP need a new route: disabling SOAP on those pages became mandatory in version 29, and Microsoft plans to remove that support in version 30.0.
Make the URL a deliberate namespace
An AL API page defines APIPublisher, APIGroup, and APIVersion. Those values form the route: api.businesscentral.dynamics.com/v2.0/{environment}/api/{publisher}/{group}/{version}/companies({companyId})/{entitySetName}. The sample uses /api/bittaapps/operations/v1.0/companies({companyId})/shipments. Changing the route is a breaking change. Choose durable camelCase names and publish a new API version when consumers cannot move without changing their code.
// Compiles against Business Central 29.0 symbols (checked 2026-11-17); not run against a tenant.
page 50100 "BA Shipment API"
{
PageType = API;
APIPublisher = 'bittaapps';
APIGroup = 'operations';
APIVersion = 'v1.0';
EntityCaption = 'Shipment';
EntitySetCaption = 'Shipments';
EntityName = 'shipment';
EntitySetName = 'shipments';
SourceTable = "Warehouse Shipment Header";
ODataKeyFields = SystemId;
DelayedInsert = true;
// Read-only feed: writes stay in codeunits behind a separate, reviewed contract.
InsertAllowed = false;
ModifyAllowed = false;
DeleteAllowed = false;
Extensible = false;
layout
{
area(content)
{
repeater(General)
{
field(id; Rec.SystemId)
{
Caption = 'id';
Editable = false;
}
field(number; Rec."No.")
{
Caption = 'number';
}
}
}
}
}SystemId is the platform-provided GUID on Business Central records and is a better integration key than a mutable document number. ODataKeyFields = SystemId makes that intent explicit; Microsoft's custom API walkthrough warns that Power Automate and Power Apps need a single GUID key. The walkthrough also sets DelayedInsert = true. Microsoft also recommends setting EntityCaption and EntitySetCaption, because those localizable captions are what the entityDefinitions metadata returns to consumers.
Separate the contract from posting logic
An API page is a transport boundary. Complex posting or orchestration belongs in tested codeunits, invoked through an appropriate supported pattern. Reuse business validation in codeunits and keep read triggers free of posting side effects.
Keep field names stable and add fields compatibly. Removing a field, changing its meaning, changing its type, or changing the key should trigger a new API version. Document nullable fields, enum values, date-time semantics, and which operations are supported. Consumers should not need to inspect AL source to understand the contract.
Design the consumer for retries
Business Central web services are stateless. The client must own correlation IDs, checkpoints, retries, and reconciliation. A timeout does not prove that the server made no change, so write operations need an idempotency strategy. Use a unique external ID enforced by storage or a durable integration ledger that rejects repeated writes. Retry HTTP 429 responses with a cool-off period, as Microsoft's API limits guidance requires, and replace heavy polling with webhooks that renew and recover.
Use Microsoft Entra ID and OAuth 2.0 for Business Central online. Basic authentication with web service access keys stopped working online after October 1, 2022. For unattended integrations, use service-to-service authentication. Give the app registration only the permissions it needs, and give its Business Central identity a least-privilege permission set.
Performance and operations are part of the API
Microsoft's AL performance guidance and our web service performance patterns cover these in depth.
Return only the fields the consumer needs and use filtering and paging instead of unbounded reads.
Prefer API pages or API queries over exposing standard UI pages.
Avoid expensive calculated fields and heavy record triggers on read paths.
Use batching deliberately; do not create parallel writes that contend for the same parent record.
Monitor incoming web-service telemetry, failures, duration, and throttling signals.
An upgrade-safe endpoint checklist
Confirm the standard v2.0 API does not already meet the requirement.
Write the request, response, keys, and error contract before the AL object.
Use a stable publisher/group/version namespace and
SystemIdwhere appropriate.Move business behavior into testable codeunits.
Add positive, negative, permission, concurrency, and retry tests.
Validate in a sandbox against the next Business Central release before production updates.
Give the integration an operational owner and a reconciliation procedure.
If you need a custom endpoint or want an inherited integration reviewed, Bitta Apps provides Business Central integration services, AL development, and ongoing support under an agreed scope.
Next step. If an integration depends on a custom endpoint nobody has reviewed recently, book the free BC Environment Snapshot: one hour on a screen share with a Business Central consultant, then a written summary of your environment within five business days.
FAQ
Frequently asked questions
How do I create a custom API in Business Central?
Create an AL page with PageType = API, or a query with QueryType = API, and set APIPublisher, APIGroup, APIVersion, EntityName and EntitySetName. For API pages, Microsoft's walkthrough also sets EntityCaption, EntitySetCaption, ODataKeyFields = SystemId and DelayedInsert = true. Publish the extension and the endpoint becomes available under its own API route.
Can I add custom fields to a standard Business Central API?
No. Microsoft states that extending APIs with additional fields isn't currently possible in Business Central. If you need extra fields, copy the AL code for the standard API and create a custom API based on it, keeping the new contract as narrow as the integration needs.
What is the URL for a custom API in Business Central online?
The pattern is api.businesscentral.dynamics.com/v2.0/{environment}/api/{publisher}/{group}/{version}/companies({companyId})/{entitySetName}. The tenant ID can optionally precede {environment}. The publisher, group and version come from the APIPublisher, APIGroup and APIVersion properties in AL. Standard Microsoft APIs use the shorter route api/v2.0.
Should I use an API page or an API query in Business Central?
Use an API page when consumers need to create, read, update or delete records, with write operations enabled only where appropriate. Use an API query when consumers only read data that joins several tables, because API queries are read-only. Both are preferred over publishing standard UI pages as web services.
How do I authenticate to a Business Central custom API?
Business Central online uses OAuth through Microsoft Entra ID. Web service access keys (basic authentication) have not been supported online since October 2022. Unattended integrations use service-to-service authentication with the client credentials flow, and requests run with the permissions assigned to the application account in Business Central.
Sources
Claims in this article were checked against the following on Nov 18, 2026.
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-develop-custom-api
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/web-services
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/api-endpoint-structure
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-api-querytype
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-disable-soap-microsoft-pages-feature-key
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/whatsnew/whatsnew-update-29-0
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/performance/performance-developer
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/dynamics-rate-limits
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/authenticate-web-services-using-oauth
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/web-service-telemetry
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/properties/devenv-delayedinsert-property
- bittaapps.com/contact?intent=snapshot
- bittaapps.com/services/al-development
- bittaapps.com/blog/business-central-web-service-performance-api-patterns
- bittaapps.com/blog/business-central-api-webhooks-renewal-recovery
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-api-pagetype
- learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/automation-apis-using-s2s-authentication
- bittaapps.com/services/integrations
- bittaapps.com/services/support