HttpClient in Business Central AL: REST API Integration Guide

Dynexal • Beginner to Intermediate • 15 min read

When Business Central needs to communicate with an external REST API, the HttpClient data type is one of the most important AL tools to understand. You can use it to send GET, POST, PUT, PATCH and DELETE requests, add headers, send JSON payloads, read responses and build integrations with websites, e-commerce platforms, middleware and other services.

What is HttpClient in Business Central?

HttpClient is the AL data type used to make outbound HTTP calls from a Business Central extension. Microsoft describes it as a wrapper around the .NET HttpClient class. It works together with related AL types such as HttpRequestMessage, HttpResponseMessage, HttpContent and HttpHeaders.

This is useful whenever Business Central must consume an external service. Typical examples include sending sales orders to an e-commerce platform, reading shipping information from a courier API, checking a payment service, synchronizing inventory with another system, or calling an AI service.

Microsoft Learn: Call external services with HttpClient

HttpClient and the related AL data types

• HttpClient: sends HTTP requests and receives responses.
• HttpRequestMessage: lets you build a request explicitly, including method, URI and headers.
• HttpResponseMessage: represents the response returned by the external service.
• HttpContent: represents request or response body content, such as JSON.
• HttpHeaders: stores HTTP header names and values.

Microsoft's HTTP and JSON API overview documents these data types as the core building blocks for service communication in AL.

Microsoft Learn: HTTP, JSON, TextBuilder and XML API overview

Important: allow outbound HttpClient requests

Outbound HTTP calls from an extension are blocked by default as a security measure. For an extension to make external calls, the Allow HttpClient Requests setting must be enabled for that app or extension in Business Central Extension Management.

Microsoft Learn: HttpClient security and configuration

HTTP methods supported by HttpClient

Business Central's HttpClient supports the common HTTP methods used in REST integrations:

• GET: retrieve data.
• POST: send data or create a resource.
• PUT: replace or create a resource according to the API contract.
• PATCH: partially update an existing resource; in AL this is commonly done through HttpClient.Send.
• DELETE: delete a resource when the external API permits it.

Choosing the method is part of the API contract. Always follow the external service's documentation rather than assuming every endpoint behaves the same way.

Simple GET request in AL

The easiest way to start learning HttpClient is with a GET request. The following example reads a public test endpoint:

procedure GetTodo() ResponseText: Text
var
    Client: HttpClient;
    Response: HttpResponseMessage;
    IsSuccessful: Boolean;
begin
    IsSuccessful := Client.Get(
        'https://jsonplaceholder.typicode.com/todos/3',
        Response);

    if not IsSuccessful then
        Error('The HTTP request could not be sent.');

    if not Response.IsSuccessStatusCode() then
        Error(
            'HTTP request failed. Status code: %1',
            Response.HttpStatusCode());

    Response.Content().ReadAs(ResponseText);
end;

The important pattern is to check both the Boolean result of the request and the HTTP status code. A request can reach the remote service and still return an error such as 400, 401 or 500.

Microsoft Learn: HttpClient.Get

Reading a JSON response

Most modern REST APIs return JSON. After reading the response into a text variable, you can parse it with AL's JSON data types.

procedure GetTodoTitle() Title: Text
var
    Client: HttpClient;
    Response: HttpResponseMessage;
    ResponseText: Text;
    JsonObject: JsonObject;
begin
    if not Client.Get(
        'https://jsonplaceholder.typicode.com/todos/3',
        Response) then
        Error('HTTP request failed.');

    if not Response.IsSuccessStatusCode() then
        Error('HTTP status code: %1', Response.HttpStatusCode());

    Response.Content().ReadAs(ResponseText);

    if not JsonObject.ReadFrom(ResponseText) then
        Error('The API returned invalid JSON.');

    JsonObject.Get('title', Title);
end;

This pattern is useful for external APIs that return objects such as customers, products, shipment updates or payment responses.

Sending JSON with POST

For POST requests, the request body is usually placed in an HttpContent variable. You can create a JSON payload as text and then send it to the endpoint.

procedure CreateCustomer() ResponseText: Text
var
    Client: HttpClient;
    Content: HttpContent;
    Response: HttpResponseMessage;
    JsonBody: Text;
begin
    JsonBody :=
        '{"name":"Dynexal Demo Customer","city":"Noida"}';

    Content.WriteFrom(JsonBody);

    if not Client.Post(
        'https://example.com/api/customers',
        Content,
        Response) then
        Error('The POST request could not be sent.');

    if not Response.IsSuccessStatusCode() then
        Error(
            'API returned HTTP %1',
            Response.HttpStatusCode());

    Response.Content().ReadAs(ResponseText);
end;

In a real integration, replace the example URL and payload with the contract documented by the external service.

Microsoft Learn: HttpClient.Post

Set the Content-Type header

When sending JSON, the external API commonly expects a Content-Type: application/json header. Content headers are accessed through HttpContent.GetHeaders.

procedure PrepareJsonContent(JsonBody: Text; var Content: HttpContent)
var
    ContentHeaders: HttpHeaders;
begin
    Content.WriteFrom(JsonBody);

    Content.GetHeaders(ContentHeaders);

    if ContentHeaders.Contains('Content-Type') then
        ContentHeaders.Remove('Content-Type');

    ContentHeaders.Add('Content-Type', 'application/json');
end;

Removing an existing Content-Type before adding the required value avoids conflicts with the default content header. The exact headers required depend on the external API.

Microsoft Learn: HttpContent.GetHeaders

Adding Authorization and other request headers

Many REST services require headers such as Authorization, Accept or a service-specific API key. You can add default headers to the HttpClient or configure headers on an explicit HttpRequestMessage.

procedure AddHeaders(var Client: HttpClient)
var
    Headers: HttpHeaders;
begin
    Headers := Client.DefaultRequestHeaders();
    Headers.Add('Accept', 'application/json');
end;

For authentication, do not hard-code real production secrets in source code. Use an appropriate credential and secret-management approach for your Business Central solution and the authentication model required by the external API.

Newer Business Central versions also support adding SecretText values to HTTP headers, which can help avoid exposing sensitive header values as ordinary text.

Microsoft Learn: HttpClient.DefaultRequestHeaders

Using HttpRequestMessage for more control

Simple GET, POST, PUT and DELETE calls can use the corresponding HttpClient methods. For scenarios where you need to control the HTTP method or request structure more explicitly, use HttpRequestMessage with HttpClient.Send.

procedure SendCustomRequest() ResponseText: Text
var
    Client: HttpClient;
    Request: HttpRequestMessage;
    Response: HttpResponseMessage;
    Headers: HttpHeaders;
begin
    Request.Method := 'PATCH';
    Request.SetRequestUri(
        'https://example.com/api/customers/1001');

    Headers := Request.GetHeaders();
    Headers.Add('Accept', 'application/json');

    if not Client.Send(Request, Response) then
        Error('The request could not be sent.');

    if not Response.IsSuccessStatusCode() then
        Error('HTTP status: %1', Response.HttpStatusCode());

    Response.Content().ReadAs(ResponseText);
end;

For PATCH requests, the request content would normally contain the fields being updated. The exact payload and headers depend on the external API.

Microsoft Learn: HttpClient.Send

PUT and DELETE requests

PUT is commonly used when an API expects a complete replacement or upsert-style request. DELETE removes a resource when permitted.

// PUT
if not Client.Put(ApiUrl, Content, Response) then
    Error('PUT request could not be sent.');

// DELETE
if not Client.Delete(ApiUrl, Response) then
    Error('DELETE request could not be sent.');

Always check Response.IsSuccessStatusCode() after the call and handle the status code according to the API contract.

Microsoft Learn: HttpClient.Put · Microsoft Learn: HttpClient.Delete

HTTP status codes you should handle

• 200 OK: request succeeded.
• 201 Created: a new resource was created.
• 204 No Content: request succeeded without a response body.
• 400 Bad Request: the request or payload is invalid.
• 401 Unauthorized: authentication is missing or invalid.
• 403 Forbidden: the caller is authenticated but lacks permission.
• 404 Not Found: the endpoint or requested resource cannot be found.
• 409 Conflict: the request conflicts with the current resource state.
• 429 Too Many Requests: the service is throttling the client.
• 500-series errors: the remote service reported a server-side problem.

Do not treat every non-200 response as the same error. Your integration should decide which errors are retryable, which require user intervention and which indicate a permanent data problem.

Common HttpClient errors and troubleshooting

“The request was blocked by the runtime”

Check the extension's Allow HttpClient Requests configuration. Outbound requests are intentionally blocked unless the extension is allowed to make them.

401 or 403 response

Check the access token, authentication scheme, scopes, API permissions and Business Central permissions. A valid token does not automatically mean the caller can access every resource.

400 or 415 response

Inspect the JSON payload and headers. A missing or incorrect Content-Type, invalid JSON or a payload that does not match the API contract can cause these responses.

Timeout

External calls take time, and Business Central sessions can remain blocked while the HTTP call completes. Use sensible timeouts and avoid putting slow external calls directly into interactive user actions when possible.

Works in Postman but not in Business Central

Compare the two requests carefully: URL, HTTP method, authorization scheme, headers, body, content type and environment. Also check the Business Central extension's outbound HTTP permission.

HttpClient timeout

The HttpClient.Timeout method gets or sets the duration before the request times out. Microsoft currently documents a default timeout of 100 seconds, subject to the Business Central Server's maximum timeout configuration.

Client.Timeout := 30000;

Use timeouts deliberately. Increasing the timeout does not fix a slow or unreliable integration; it only makes the calling session wait longer.

Microsoft Learn: HttpClient.Timeout

Performance considerations

External HTTP calls can make an AL session wait until the request completes. If a user launches a page action that makes a slow external call, the UI can appear to hang while the server waits.

For integrations that do not need an immediate user response, consider an asynchronous architecture such as a job queue or an integration layer. Batch work where appropriate instead of making hundreds of individual calls from an interactive action.

Microsoft also provides outgoing web service request telemetry for HttpClient calls, which can help identify failures and performance problems.

Real-world example: synchronizing a Business Central customer

Imagine an external CRM exposes this endpoint:

POST https://crm.example.com/api/customers

When a new Business Central customer is created, an integration can build a JSON payload such as:

{
  "externalId": "8b6b9c1a-...",
  "number": "10000",
  "name": "Dynexal Customer",
  "city": "Noida"
}

The AL solution can then:

1. Read the required Customer fields.
2. Create the JSON payload.
3. Prepare HttpContent and the required headers.
4. Send the POST request through HttpClient.
5. Check the HTTP status code.
6. Parse the response if the CRM returns an external ID.
7. Log or queue the failure when the external service is unavailable.

For production systems, it is usually better to separate the integration logic into dedicated codeunits rather than placing a large HTTP implementation directly inside a table trigger.

HttpClient best practices

• Keep external API calls inside focused integration codeunits.
• Use HttpResponseMessage status codes instead of assuming every request succeeded.
• Validate JSON before reading properties.
• Set the correct Content-Type for request bodies.
• Never hard-code production passwords, client secrets or access tokens in AL source code.
• Use appropriate authentication and permission models.
• Handle 429 and transient 5xx failures with controlled retry strategies where appropriate.
• Do not retry validation errors such as most 400 responses without fixing the payload.
• Keep user-interface actions responsive by moving slow integrations to background processing where practical.
• Log enough information to troubleshoot failures without storing sensitive credentials or personal data unnecessarily.
• Test integrations with non-production data before enabling them for live customers.
• Monitor outgoing web service telemetry in production environments.

HttpClient vs Business Central APIs

These two concepts are related but different:

• Business Central API: an external application calls Business Central to read or modify ERP data.
• HttpClient: Business Central calls an external service from AL.

In a two-way integration, you may use both. For example, an external website could call a Business Central API to read inventory, while Business Central uses HttpClient to send shipment updates back to the website.

Quick learning checklist

1. Learn HTTP methods and status codes.
2. Practice HttpClient.Get with a public test API.
3. Learn HttpContent and JSON request bodies.
4. Learn request and content headers.
5. Practice POST, PUT and DELETE.
6. Learn HttpRequestMessage and HttpClient.Send for advanced requests such as PATCH.
7. Understand authentication and permissions.
8. Move integration code into dedicated codeunits.
9. Add logging, retries and monitoring before production use.

What should you learn next?