Business Central - Automation APIs

Business Central provides automation APIs which can be used to create a new company on the tenant, running RapidStart packages, installing extensions, adding users to user groups and assigning permission sets to users.

Delegated admin credentials and Dynamics 365 Business Central users with permissions, can call the APIs.

For delegated admin access, you must add the Azure Active Directory (Azure AD) application to the AdminAgents group. If the Azure AD application is not added, the consent flow will show an error such as Need pre-consent. For more information, see Pre-consent your app for all your customers in the Graph documentation.

Automation APIs are placed in the microsoft/automation API namespace. In all the examples below, parameters are marked in parenthesis {}. Make sure that only valid parameters are passed.

Create a Company

To create a company, an automationCompany endpoint is available. To create a Company issue a POST request as shown in the following example.

POST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/{apiVersion}/companies({companyId})/automationCompanies

Authorization: Bearer {token}

Content-type: application/json

{

    "name": "CRONUS India",

    "displayName": "CRONUS India Ltd.",

    "businessProfileId": ""

}

The {companyId} must be the ID of an valid company on the tenant. Issue a GET automationCompany request to fetch existing companies. 

For Example: Retrieves the properties and relationships of an automationCompany object for Dynamics 365 Business Central.

Http Request: 

GET /microsoft/automation/{apiVersion}/companies({{companyid}})/automationCompanies
Header: Authorization
Value: Bearer {token}

Http Response:

If successful, this method returns a 200 OK response code and list of automationCompany objects in the response body. For example:

{

    "id": "3496bbf8-fcae-4e48-a4f8-cb17c27de0b3",

    "name": "CRONUS India",

    "evaluationCompany": true,

    "displayName": "CRONUS India Ltd.",

    "businessProfileId": ""

}

Note: The company which is created will not be initialized.

To rename a company, issue a PATCH automationCompanies.

Upload and apply a RapidStart package

RapidStart is uploaded, installed, and applied using the APIs described below. RapidStart operations can be time consuming. To get the current status of the RapidStart packages and running operations issue a GET configurationPackages as shown in the following example.

GET https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/{apiVersion}/companies({companyId})/configurationPackages

Authorization: Bearer {token}

In the response, status for the import and apply status will be shown, as well as information about the RapidStart package.

Insert RapidStart

First step is to create the configuration package, by issuing a POST configurationPackages in the Dynamics 365 Business Central tenant. Once the configuration package is created, the RapidStart package can be uploaded. See the example below.

POST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/{apiVersion}/companies({companyId})/configurationPackages

Authorization: Bearer {token}

Content-type: application/json

{

    "code":"{SAMPLE}",

    "packageName": "{SAMPLE}"

}

Upload RapidStart package

Once the configuration package is created, a RapidStart package can be uploaded with a PATCH configurationPackages. See the example below.

PATCH https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/{apiVersion}/companies({{companyId}})/configurationPackages('{SAMPLE}')/file('{SAMPLE}')/content

Authorization: Bearer {token}

Content-type: application/octet-stream

If-Match: *

Body: RapidStart file.

Import and apply RapidStart package

Once uploaded, the RapidStart package needs to be imported by issuing a POST on the bound action Microsoft.NAV.import.

POST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/{apiVersion}/companies({{companyId}})/configurationPackages('SAMPLE}')/Microsoft.NAV.import

Authorization: Bearer {token}

When the RapidStart package is imported it can applied with a POST on bound action Microsoft.NAV.apply.

POST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/{apiVersion}/companies({companyId})/configurationPackages('SAMPLE}')/Microsoft.NAV.apply

Authorization: Bearer {token}

Managing users, user groups, and permission sets

The automation APIs enable users to be set up in Dynamics 365 Business Central.

Modifying user properties

Get the current user properties by issuing a GET users. This will get the UserSecurityId needed on subsequent requests.

To modify the user, create a PATCH user request as shown in the example below.

PATCH https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v1.0/companies({id})/users({userSecurityId})

Content-type: application/json

If-Match:*

{

    "state": "Enabled",

    "expiryDate": "2025-10-01T00:10:59.999Z"

}

Assign user permissions and user groups

To assign users to a user group, issue a POST request against the userGroupMembers entity. See the example below.

POST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/{apiVersion}/companies({companyId})/users({userSecurityId})/userGroupMembers

Authorization: Bearer {token}

{ 

    "code": "D365 EXT. ACCOUNTANT",

    "companyName" :"CRONUS Inida"

}

To retrieve the list of user groups issue a GET userGroups. This will return the information that you need for the payload above.

Assigning permission sets is identical to adding users to user groups. GET permissionSet returns information about the available permission sets. To assign a permissionSet issue a POST userPermission as shown in the following example.

POST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/{apiVersion}/companies({companyId})/users({userSecurityId})/userPermissions

Authorization: Bearer {token}

{ 

    "id": "SECURITY"

}

Removing the permissionSet from the user is done by issuing a DELETE userPermissions on the users entity.

Handling tenant extensions

Add-on extensions which are already published to the tenant can be installed and uninstalled. Per-tenant extensions can be uploaded and installed. To get the list of all extensions on the tenant, issue a GET extensions. This will return the packageId needed for installing and uninstalling extensions.

Installing and uninstalling published add-on extensions

There are two bound actions available on the extensions endpoint: Microsoft.NAV.install and Microsoft.NAV.uninstall.

Issue a POST extension using the bound actions. See the example below.

POST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/{apiVersion}/companies({companyId})/extensions({packageId})/Microsoft.NAV.install

Authorization: Bearer {token}

Upload and install a per-tenant extension

Issue a PATCH against the extensionUpload endpoint to upload and install the extension.

Note: Installing per-tenant extensions using Automation APIs is only possible in SaaS.

Uninstalling the extension can be done through the bound action Microsoft.NAV.uninstall, as with the add-on extensions.

Monitoring extension installation progress

To view ongoing extension installation status, issue GET extensionDeploymentStatus as shown in the following example.

GET https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v1.0/companies({companyId})/extensionDeploymentStatus

Blog Source: Microsoft Docs