Business Central Custom API Endpoint Using AL

Business Central Custom API Endpoint Guide

Business Central does not expose all tables via standard APIs.

To access custom data, you must create API endpoints using AL language and deploy them as extensions.

Whenever Microsoft does not provide the API you need, the only option is to build a custom API using AL Language and deploy it as an extension.

This document explains how to create the extension, build the package, and install it in your Business Central environment.

This guide explains how to build, package, and deploy custom API endpoints in Business Central step by step.

When Do You Need Custom API Endpoints in Business Central?

Custom API endpoints in Microsoft Dynamics 365 Business Central are required when the default APIs do not provide the data structure or flexibility needed for your specific business or integration use case.

While standard APIs cover common scenarios, many actual implementations need customization.

When Required Tables Are Not Available in the Default API

Business Central does not expose all tables through its standard API layer. This becomes a limitation when:

• You need access to custom tables or fields.
• Required data exists, but is not part of the default API endpoints.
• You want to retrieve specific business logic-driven data.

In such cases, custom API endpoints allow you to directly expose the required tables and fields using AL, without depending on limited standard APIs.

When Working with Custom Extensions

If your Business Central environment includes custom extensions, the data introduced through those extensions is not automatically available via standard APIs.

Custom endpoints help you:

• Expose extension-based data models.
• Maintain consistency between custom logic and API output.
• Ensure your integrations can fully utilize extended functionality.

This is especially important for businesses that rely on custom workflows or industry-specific customizations.

When Building Third-Party Integrations

Custom endpoints become necessary to:

• Structure data in a way that matches the target system
• Reduce multiple API calls by creating optimized endpoints.
• Handle complex data mapping and transformations.

This ensures smoother, more reliable integrations without adding unnecessary complexity on the external system side.

Prerequisites

• Visual Studio Code is installed on your machine
• The AL Language extension is installed in Visual Studio Code
• A Business Central account where you can publish the extension

How to Create Custom API Pages in Business Central Using AL

A custom API endpoint in Business Central is usually created by defining an API Page in AL. This API Page controls which table, fields, and records are exposed to external systems.

Custom API pages are useful when the standard Business Central APIs do not expose the data required for your integration. For example, you may need to expose custom tables, extension fields, calculated values, or integration-specific data structures.

To create a custom API page, you need to define the page type as API, assign the API publisher, API group, API version, entity name, and entity set name. These properties define how the endpoint will appear and how external systems will access it.

Key Properties of a Business Central API Page

Below are the important properties used while creating a custom API page in AL:

Using these properties correctly is important because they directly affect the final API endpoint URL and how the data is consumed by third-party systems.

Sample AL Code for a Custom API Page

Here is a basic example of a custom API page in AL:

page 50100 CustomerCustomAPI
{
    PageType = API;
    APIPublisher = 'satva';
    APIGroup = 'custom';
    APIVersion = 'v1.0';
    EntityName = 'customCustomer';
    EntitySetName = 'customCustomers';
    SourceTable = Customer;
    DelayedInsert = true;

    layout
    {
        area(content)
        {
            repeater(Group)
            {
                field(id; Rec.SystemId)
                {
                    Caption = 'Id';
                }

                field(number; Rec."No.")
                {
                    Caption = 'Number';
                }

                field(name; Rec.Name)
                {
                    Caption = 'Name';
                }

                field(email; Rec."E-Mail")
                {
                    Caption = 'Email';
                }
            }
        }
    }
}

In this example, the API page exposes selected customer fields through a custom endpoint. You can modify the source table and fields based on your integration requirement.

How to Build an API Package File Using AL Language in Business Central

1. Open your AL project folder (the BC App Repo) in Visual Studio Code.
2. Open the app.json file and increase the version number by 1. Business Central will not install an extension if the version is the same as an already-installed one.
3. All your API pages, tables, and other AL objects will be visible in the project. From here you can:
   • Edit API Page objects.
   • Add new fields
   • Expose new data
   • Adjust logic
4. Once done, build the package using Ctrl + Shift + B. VS Code will generate a new .app file, and the output window will confirm the package has been created.
5. When you build, VS Code will show two environment options. Choose: Microsoft Cloud Sandbox.
6. You will get a prompt click on “Copy & Open”.
7. On the page that opens, paste the code you copied in the previous step.
8. Sign in to your BC account by entering your Azure Credentials.

Once all of the above steps are completed, you will be able to build your app, and a package will be generated.

How to Grant Extension Permissions in Business Central

The user installing the extension must have extension management rights. Follow these steps:

1. In the Business Central client, search for “Users” and open the page.
2. Open the user you want to grant permission to and click on “Effective Permissions”.
3. Click on “Permissions Sets”.
4. Click on “Edit List”, search for “Extension Management Admin”, and click the arrow to include it in the permission sets.

How to Install and Uninstall Extensions in Business Central

1. In the Business Central client, search for “Extension Management” and open the page.
2. Click on “Upload Extension”.
3. Select the .app file, enable the radio button shown, and click the Deploy button.

4. A message will display indicating the upload is in progress.
5. Search for “Extension Installation Status” to check the upload status. It takes around 5 minutes to complete.
6. Once the upload is complete, the status will change to “Completed”.
7. To uninstall the application, search for it in “Extension Management” and click on “UnPublish”.

How to Test the Custom API Endpoint in Business Central

Once the extension is installed, the next step is to test whether the custom API endpoint is working correctly.

You can test the API endpoint using tools like Postman or any REST client. Before testing, make sure you have the correct Business Central environment name, company ID, API publisher, API group, API version, and entity set name.

A typical Business Central custom API endpoint follows this structure:

https://api.businesscentral.dynamics.com/v2.0/{tenant-id}/{environment-name}/api/{publisher}/{group}/{version}/companies({company-id})/{entity-set-name}

Before calling the endpoint, confirm the following:

• The extension is installed successfully.
• The API page is included in the published .app file.
• The user has the required permissions.
• The company ID is correct.
• The entity set name matches the value defined in AL.
• Authentication is configured correctly.

If the endpoint returns data, your custom API page is working as expected. If it returns an authorization or not found error, check the permission set, endpoint URL, API page properties, and extension installation status.

Standard API vs Custom API in Business Central

Business Central does not provide API endpoints for all tables. Many functional areas — especially custom tables, custom fields, or certain financial/operational tables are not exposed through Microsoft’s default API set.

Examples of data that require custom endpoints:

• Custom master tables
• Custom workflows
• Custom posting tables
• Extra fields added via extensions
• Industry-specific data
• Anything outside the base API group

Because of this, integrations often require:

• Custom API Pages
• Custom entities
• API Groups / Versions
• Additional logic inside AL

Creating a custom endpoint ensures you can expose exactly what your integration needs.

Common Errors While Deploying Custom API Extensions

While creating and deploying custom API endpoints in Business Central, you may face a few common errors. Most of them are related to versioning, permissions, environment setup, or incorrect API page properties.

Same Extension Version Already Installed

Business Central will not install the same extension version again. If you are updating an existing extension, increase the version number in the app.json file before building the package.

Missing Extension Management Permission

If the user does not have permission to manage extensions, the installation may fail. Assign the required extension management permission set before uploading the .app file.

API Endpoint Not Found

This usually happens when the endpoint URL is incorrect or the API page properties do not match the URL. Check the API publisher, API group, API version, entity name, and entity set name.

Custom Fields Not Visible in API Response

If custom fields are not visible, confirm that the fields are added inside the API page layout. Fields available in the source table will not automatically appear in the API response unless they are exposed in the API page.

Authentication Error

Business Central APIs require proper authentication. If the API request fails due to authentication, check the access token, tenant details, environment name, and user permissions.

Conclusion

When the standard Business Central APIs do not cover your requirements, creating a Custom API via AL is the official and correct approach.

Using the steps above, you can build your AL app, package it, install it, and expose any data you need via custom APIs.

FAQ

When should you use custom APIs in Business Central?

You should use custom APIs when the required data is not available in the standard API, especially for custom tables, workflows, or integration-specific data.

What is the difference between standard API and custom API in Business Central?

Standard APIs provide predefined endpoints for common data, while custom APIs allow you to expose specific tables, fields, and business logic using AL language.

Can custom APIs improve Business Central integrations?

Yes, custom APIs allow you to access specific data and tailor integrations to your requirements, making them more efficient and scalable.

Do I need AL language to create API endpoints in Business Central?

Yes, AL language is required to define API pages, structure data, and create custom endpoints in Business Central.

Does Business Central support all tables in its standard API?

No, Business Central only exposes a limited set of tables through its standard API. Custom tables and extension-based data require custom API endpoints.

Why can’t I use the standard Business Central API for all tables?

Microsoft only exposes a subset of Business Central tables through the default API. Custom tables, extension-added fields, and many financial/operational tables require you to build custom API pages using AL Language.

What happens if I don’t increment the version number in app.json?

Business Central will reject the installation if the version number matches an already-installed extension. Always increment the version in app.json before building a new package.

Do I need a sandbox environment to build the package?

Yes, a sandbox environment is required for the build and deployment process. The AL Language extension in VS Code connects to the sandbox to compile and validate your extension.

How long does extension installation take?

Extension installation typically takes around 5 minutes. You can monitor the progress by searching for “Extension Installation Status” in the Business Central client.