Web Services and Multiple Production Environments with Dynamics 365 Business Central

The 2019 Wave 2 release of Business Central Online in October introduces the ability to create multiple production environments for each Azure Active Directory tenant. This provides companies with divisions in multiple countries the option to create a separate Business Central environment in other countries in which they have a business presence.

An integral part of this effort has been to version our web service endpoints to v2.0 so that you can use web services with each production environment. We have updated the routing of the services to be compatible with additional environments. This change applies to the base URL of all Business Central web service, including APIs, OData, and SOAP endpoints. Version 2.0 of these web services includes an environment parameter that is required to route the call to the correct resource in the selected environment.

What’s new in the v2.0 endpoint

Version 1.0 of the web services will continue to be compatible only with a single production environment named “Production” and a single sandbox environment. Any connected apps or other web service integrations must use v2.0 of the endpoints to be compatible with multiple production and sandbox environments. The primary difference to account for in the new endpoint is the required environment parameter in the URL. This was previously an optional parameter. The v1.0 endpoint would redirect to the Production environment by default if the environment was not specified. You must now specify an environment in the URL, even for Production.

For example, if you are using the companies resource type through the API endpoint, it must be updated to v2.0 and include the environment name as shown in the following example:

https://api.businesscentral.dynamics.com/v2.0/<Azure AD tenant ID>/<ENVIRONMENT NAME>/api/v1.0/companies

Note that the Azure AD tenant ID is still optional if it can be determined based on the auth token. However, failing to specify an environment name will result in a 400 error.

Next steps

The new web service endpoint is available in production already now. Update any apps or integrations you have to v2.0 as soon as possible to ensure their compatibility with multiple environments when they become available.

See our online documentation for more information on creating connected apps or web service integrations for Business Central: