How-ToIntegrations

How to Use Web Services in Business Central

Expose Business Central pages and codeunits as SOAP or OData web services for integration with external systems.

Stein Sæstad
7 min read

Business Central lets you publish pages and codeunits as web services, making them accessible to external applications. There are two protocols available: OData (used for data access and list-style integrations) and SOAP (used for calling codeunit functions). Both are available in cloud and on-premises deployments.

For new integrations, API pages are the recommended approach for read/write data access, they follow a cleaner OData v4 standard. Web services are still useful for exposing codeunit logic or for quick access to pages that have no API page, but SOAP is deprecated, so new work should use OData v4 or API pages.

SOAP Changes in Version 29

Starting with version 29.0 (2026 release wave 2), Disable SOAP web services on Microsoft UI pages is no longer optional in Feature Management. Microsoft UI pages, such as the Customer Card or Item List, can no longer be called through a SOAP endpoint, and there is no setting to turn this back on.

This change targets Microsoft UI pages. Codeunits published as SOAP services keep working for now, but SOAP as a whole is deprecated and will be removed in a later release. Before you schedule the version 29 update:

  1. Open the Web Services page and look for Microsoft pages that external systems call over SOAP.
  2. Check integration middleware, Power Automate flows, and custom code for SOAP URLs that point to pages.
  3. Move those integrations to the OData v4 URL of the same page, or to an API page.
  4. Plan the same move for SOAP codeunit services, so the later removal does not catch you out.

If an integration needs a stable page-based interface, an API page or a copy of the page in a per-tenant extension is a safer target than a Microsoft UI page.

  1. Search for Web Services using Alt + Q.
  2. The page lists all currently published services. Each row shows the object type, object name, service name, and whether it is published.

Publishing a Page as an OData Web Service

  1. On the Web Services page, select New to add a row.
  2. Set Object Type to Page.
  3. Set Object ID to the page number you want to expose, for example, 21 for the Customer Card or 22 for the Customer List.
  4. Enter a Service Name. This becomes part of the URL, so keep it short and descriptive (e.g. Customers).
  5. Check the Published checkbox.
  6. The OData URL will appear in the OData URL column once the row is saved.

The OData URL follows this pattern for cloud environments:

https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environment}/ODataV4/{ServiceName}?company={CompanyName}

For on-premises, the URL uses your server hostname instead.

Publishing a Codeunit as a SOAP Web Service

SOAP services are used when you need external systems to call specific functions defined in a codeunit. SOAP is deprecated, so for new integrations publish the codeunit as an OData v4 unbound action instead, and keep SOAP for existing callers you cannot change yet.

  1. On the Web Services page, select New.
  2. Set Object Type to Codeunit.
  3. Set Object ID to the codeunit number.
  4. Enter a Service Name.
  5. Check Published.

The SOAP URL will appear in the SOAP URL column. External callers can consume the WSDL from that URL to discover available functions and their parameters.

Consuming a Web Service from an External Application

How you consume the service depends on the protocol:

OData: Make HTTP GET or POST requests to the OData URL. You can use tools like Postman, Power Query, or any HTTP client. The service returns JSON or XML depending on the Accept header you send.

SOAP: Import the WSDL into your application (for example, using Visual Studio’s “Add Service Reference” or a SOAP client library). The generated client will expose the codeunit’s functions as callable methods.

Authentication

All web service calls require authentication. Business Central supports:

  • OAuth 2.0, required for cloud environments. Use an Azure AD app registration to obtain a bearer token.
  • Basic Auth with web service access key, available for on-premises and supported in cloud for backward compatibility. The web service access key is generated on the User Card under Web Service Access Key.

Avoid using Basic Auth in new integrations if your environment supports OAuth 2.0.

Notes on OData Web Services vs. API Pages

OData web services expose the full page object, including all fields visible on the page. API pages are purpose-built for integration and expose a defined, stable set of fields. If you are building a new integration that reads or writes master data (customers, vendors, items), use an API page rather than a web service. OData web services remain useful for quick access to data from specific pages that do not have a corresponding API page. From version 29, those pages can only be reached through OData, not SOAP.

To build a more structured read/write integration using the Business Central REST API, see How to Use APIs in Business Central.