How to add custom fields to the standard Business Central APIs

In Microsoft Dynamics 365 Business Central, custom fields (whether added through AL table extensions, partner extensions, or ISV extensions from AppSource) are not automatically exposed by the standard REST API. Adding a custom field to a table requires a custom API page to expose it on a new endpoint before it can be read through the API. This guide explains why, what your options are inside Business Central, and how Skuno BI removes the requirement entirely.

Why custom fields aren’t exposed automatically

The Business Central REST API is page-based, not table-based. The API v2.0 endpoints (customers, items, salesOrders, and the rest) are each backed by an API page in AL. An API page is an object that explicitly declares which table fields are included in the response and which are writable. Adding a column to a table doesn’t change the API page; the page still emits the same JSON it was designed to emit, with the same field set.

This design has real benefits: Microsoft can guarantee a stable schema across releases, and developers can change the underlying table without breaking integrations. The cost is that exposing a field becomes the responsibility of whoever added it. If you bought an ISV app that adds a Loyalty Points column to Customer, you need to ask the vendor to create a new API page which includes the field (or write one yourself) before your integration can read it.

The historical workaround was to publish a standard page (e.g. the Customer Card) as an OData web service, which would emit whatever fields the page itself displayed. Microsoft is deprecating that pattern, and the property names it produced were always unstable (derived from AL captions and prone to break when the page was edited). New integrations should not rely on it.

Creating a custom API page

The standard Microsoft API pages (APIV2 - Customers, APIV2 - Items, and so on) cannot be extended. AL’s pageextension object only works against pages with PageType of Card, List, Worksheet, and similar. It does not work against PageType = API. There is no supported way to add a field to one of Microsoft’s existing API endpoints.

To expose a custom field, you have to author a brand new API page in AL with PageType = API, declaring its source table and the fields to expose. This gives you full control over property naming, OData annotations, and which operations are allowed (read, insert, modify, delete). The new page lives at its own URL, /api/{APIPublisher}/{APIGroup}/{APIVersion}/companies({id})/{EntitySetName}. The standard /api/v2.0/ endpoints are unchanged and still emit Microsoft’s original schema.

This is the right approach if you are comfortable with developing and deploying your own Business Central extension in AL on every tenant that needs the field, and if your integration falls within Business Central’s API limits. You’ll also need to maintain this page whenever the underlying table is affected by a Business Central update, and re-publish a new page for each API version you want to support.

How Skuno BI exposes custom fields

Skuno BI operates on a continuously-synchronised copy of your Business Central database, surfaced as a tenant-scoped OData v4 endpoint at https://<tenant>.skuno.app/api/v2.0/odata/bc/. Because the sync runs at the table level rather than the page level, every column on every table is visible to Skuno BI, including any custom field added via AL, a configuration package, or an ISV app.

When Skuno BI serves a row from any table, the response is a superset of the base BC table schema. It includes:

• Every standard Microsoft field
• Every FlowField, evaluated server-side at read time
• Every custom field on the base table
• Every field added by table extensions (your own or any installed ISV app)

Field names follow a consistent normalisation rule: non-alphanumeric characters in the AL field name are replaced with underscores, and the original casing is preserved. A custom field declared in AL as "Loyalty Points" (field 50100 on the Customer table) appears in the response as Loyalty_Points. Types are mapped automatically into OData, and the $metadata document at the endpoint root publishes the exact schema for whatever extensions are deployed on that tenant.

There’s no AL development involved and no per-field configuration to do. The first sync after a new field appears on the table picks it up automatically.

Practical example: a Loyalty Points custom field

Suppose you’ve added a Loyalty Points field (field 50100, Decimal) to the Customer table via a table extension named Loyalty Customer Ext. The three sections below show what the standard endpoint returns, what a custom API page looks like, and what Skuno BI returns without any AL work.

Microsoft API v2.0: not exposed, and the page can’t be extended

GET /api/v2.0/companies({id})/customers({customerId})

{
  "id": "...",
  "number": "10000",
  "displayName": "Cannon Group",
  "type": "Company",
  // ... standard fields only
  // loyaltyPoints is NOT here, and there's no way to add it to this endpoint
}

The APIV2 - Customers page is PageType = API, which AL’s pageextension object refuses to extend. There’s no way to make Microsoft’s /api/v2.0/customers emit loyaltyPoints.

Custom API page: a new endpoint with the field

page 50100 "Customer With Loyalty API"
{
    PageType = API;
    SourceTable = Customer;
    APIPublisher = 'contoso';
    APIGroup = 'crm';
    APIVersion = 'v1.0';
    EntityName = 'customer';
    EntitySetName = 'customers';
    DelayedInsert = true;
    ODataKeyFields = SystemId;

    layout
    {
        area(content)
        {
            repeater(Group)
            {
                field(id; Rec.SystemId) { }
                field(number; Rec."No.") { }
                field(displayName; Rec.Name) { }
                field(loyaltyPoints; Rec."Loyalty Points") { }
            }
        }
    }
}

After publishing this AL extension to every tenant that needs it, the field is reachable at a new URL. Microsoft’s /api/v2.0/customers endpoint is unaffected:

GET /api/contoso/crm/v1.0/companies({id})/customers({customerId})

{
  "id": "...",
  "number": "10000",
  "displayName": "Cannon Group",
  "loyaltyPoints": 1250.00
}

Skuno BI: exposed automatically

GET https://mycompany.skuno.app/api/v2.0/odata/bc/Customer_18
    ?$filter=No eq '10000'
    &$select=No,Name,Loyalty_Points

{
	"@odata.context": "https://mycompany.skuno.app/api/v2.0/odata/bc/$metadata#Customer_18",
	"value": [
		{
			"No": "10000",
			"Name": "Cannon Group",
			"Loyalty_Points": "1250"
		}
	]
}

The endpoint is addressed by table name and number (Customer_18), the custom field appears alongside the standard ones, and no page extension, AL deployment, or environment configuration was required.

Gotchas

API pages can’t be extended, only re-authored. AL’s pageextension object only applies to pages with PageType of Card, List, Worksheet, and friends. Microsoft’s APIV2 - Customers, APIV2 - Items, and the rest are PageType = API and can’t be extended. To expose a custom field, you must build a brand new API page from scratch and publish it under your own APIPublisher/APIGroup/APIVersion. The standard endpoints stay as they are.

Each API page is its own URL. A new API page doesn’t add fields to /api/v2.0/customers. It creates a new endpoint at /api/{publisher}/{group}/{version}/.... If your integration is consuming /api/v2.0/customers, it has to be repointed at the new path to see the custom field.

Flowfields on custom tables can be expensive. Custom fields that are flowfields (CalcFormula-based) are calculated on every read. Exposing them via API for high-volume integrations can cause unexpected database load, especially when the calculation joins against large transaction tables like Item Ledger Entry.

When to use which approach

A custom API page in AL is the right answer when you’ve added a domain object that doesn’t fit any existing endpoint, and your consumer needs a Microsoft-native API surface. That usually means a Power Automate flow, a Microsoft 365 add-in, or anything else that expects to authenticate through Entra ID against api.businesscentral.dynamics.com. You’re trading ongoing AL maintenance for that integration fit.

Skuno BI is the better fit when there are lots of custom fields, when those fields keep changing, or when you need the same shape of data across several tenants. The sync picks new fields up on its own and the OData endpoint is the same shape on every tenant, so an integration written against one customer’s data works against the next without per-tenant code.

Learn more about how Skuno BI surfaces Business Central data →