{"title":"Introduction to automation APIs","url":"https://jonas-paprotka.de/docs/dev-itpro/administration/itpro-introduction-to-automation-apis/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/itpro-introduction-to-automation-apis, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/itpro-introduction-to-automation-apis","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn how automation APIs create companies, apply configuration packages, manage extensions, assign permissions, and inspect security settings.","date":"2026-08-05","meta":{"topic":"concept-article"},"outline":[{"level":2,"title":"Create a company","slug":"create-a-company","at":1039,"chars":800},{"level":2,"title":"Upload and apply a RapidStart package","slug":"upload-and-apply-a-rapidstart-package","at":1839,"chars":2525},{"level":3,"title":"Insert RapidStart","slug":"insert-rapidstart","at":2489,"chars":569},{"level":3,"title":"Upload RapidStart package","slug":"upload-rapidstart-package","at":3058,"chars":512},{"level":3,"title":"Import and apply RapidStart package","slug":"import-and-apply-rapidstart-package","at":3570,"chars":794},{"level":2,"title":"Managing users and permission sets","slug":"managing-users-and-permission-sets","at":4364,"chars":3261},{"level":3,"title":"Modifying user properties","slug":"modifying-user-properties","at":4469,"chars":538},{"level":3,"title":"Assign user permissions and user groups","slug":"assign-user-permissions-and-user-groups","at":5007,"chars":1533},{"level":3,"title":"Get new users from Office 365","slug":"get-new-users-from-office-365","at":6540,"chars":1085},{"level":2,"title":"Inspect security and permissions","slug":"inspect-security-and-permissions","at":7625,"chars":1593},{"level":2,"title":"Handling tenant extensions","slug":"handling-tenant-extensions","at":9218,"chars":4604},{"level":3,"title":"Installing and uninstalling published add-on extensions","slug":"installing-and-uninstalling-published-add-on-extensions","at":9559,"chars":559},{"level":3,"title":"Unpublishing an uninstalled app","slug":"unpublishing-an-uninstalled-app","at":10118,"chars":781},{"level":3,"title":"Upload and install a per-tenant extension","slug":"upload-and-install-a-per-tenant-extension","at":10899,"chars":617},{"level":3,"title":"Insert extension upload","slug":"insert-extension-upload","at":11516,"chars":730},{"level":3,"title":"Upload extension file","slug":"upload-extension-file","at":12246,"chars":489},{"level":3,"title":"Install extension","slug":"install-extension","at":12735,"chars":749},{"level":3,"title":"Monitoring extension installation progress","slug":"monitoring-extension-installation-progress","at":13484,"chars":338},{"level":2,"title":"Handling Feature Management","slug":"handling-feature-management","at":13822,"chars":1547},{"level":3,"title":"Get a list of available features","slug":"get-a-list-of-available-features","at":13853,"chars":311},{"level":3,"title":"Activate a feature","slug":"activate-a-feature","at":14164,"chars":665},{"level":3,"title":"Deactivate a feature","slug":"deactivate-a-feature","at":14829,"chars":540},{"level":2,"title":"Related information","slug":"related-information","at":15369,"chars":758}],"text":"Automation APIs provide capability for automating company setup through APIs. Once the tenants are created, the automation APIs can be used, in order to hydrate the tenant - to bring the tenant up to a desired state. Usually this involves creating a new company on the tenant, running RapidStart packages, installing extensions, assigning permission sets to users, and managing security groups.\nDelegated admin credentials and Business Central users with permissions, can call the APIs.\n> IMPORTANT\n> For delegated admin access, you must add the Microsoft Entra application to the AdminAgents group. If the Microsoft Entra application is not added, the consent flow will show an error such as Need pre-consent. See https://learn.microsoft.com/graph/auth-cloudsolutionprovider#pre-consent-your-app-for-all-your-customers in the Graph documentation.\nAutomation 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.\n## Create a company\nTo create a company, an automationCompany endpoint is available. To create a company, issue a POST request<api/dynamics_automationcompany_create> as shown in the following example.\n```json\nPOST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/automationCompanies\nAuthorization: Bearer {token}\nContent-type: application/json\n{\n    \"name\": \"CRONUS\",\n    \"displayName\": \"CRONUS\",\n    \"businessProfileId\": \"\"\n}\n```\nThe {companyId} must be the ID of a valid company on the tenant. Issue a api/dynamics_automationcompany_get request to fetch existing companies.\n> NOTE\n> The company, which is created won't be initialized.\nTo rename a company, issue a PATCH automationCompanies<resources/dynamics_automationcompany>.\n## Upload and apply a RapidStart package\nRapidStart 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<resources/dynamics_configurationpackage> as shown in the following example.\n```json\nGET https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages\n\nAuthorization: Bearer {token}\n```\nIn the response, status for the import and apply status is shown, and information about the RapidStart package.\n### Insert RapidStart\nFirst step is to create the configuration package, by issuing a POST configurationPackages<api/dynamics_configurationpackage_create> in the Business Central tenant. Once the configuration package is created, the RapidStart package can be uploaded. See the example below.\n```json\nPOST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages\n\nAuthorization: Bearer {token}\nContent-type: application/json\n{\n    \"code\":\"{SAMPLE}\",\n    \"packageName\": \"{SAMPLE}\"\n}\n```\n### Upload RapidStart package\nOnce the configuration package is created, a RapidStart package can be uploaded with a PATCH configurationPackages<api/dynamics_configurationpackage_update>. See the example below.\n```json\nPATCH https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages({packageId})/file('{SAMPLE}')/content\n\nAuthorization: Bearer {token}\nContent-type: application/octet-stream\nIf-Match: *\nBody: RapidStart file.\n```\n### Import and apply RapidStart package\nOnce uploaded, the RapidStart package needs to be imported by issuing a POST on the bound action Microsoft.NAV.import<api/dynamics_configurationpackage_create>.\n```json\nPOST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages({packageId})/Microsoft.NAV.import\n\nAuthorization: Bearer {token}\n```\nWhen the RapidStart package is imported, it can be applied with a POST on bound action Microsoft.NAV.apply<api/dynamics_configurationpackage_create>.\n```json\nPOST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages({packageId})/Microsoft.NAV.apply\n\nAuthorization: Bearer {token}\n```\n## Managing users and permission sets\nThe automation APIs enable users to be set up in Business Central.\n### Modifying user properties\nGet the current user properties by issuing a api/dynamics_user_get. This gets the UserSecurityId needed on subsequent requests.\nTo modify the user, create a PATCH user<api/dynamics_user_update> request as shown in the example below.\n```json\nPATCH https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/users({userSecurityId})\nContent-type: application/json\nIf-Match:*\n{\n    \"state\": \"Enabled\",\n    \"expiryDate\": \"2035-01-01T21:03:53.444Z\"\n}\n```\n### Assign user permissions and user groups\n> NOTE\n> User groups are replaced with https://learn.microsoft.com/dynamics365/release-plan/2023wave1/smb/dynamics365-business-central/manage-user-permissions-using-security-groups and will be deprecated in version 25. See security group APIs<resources/dynamics_securitygroup>.\nTo assign users to a user group, issue a POST request<api/dynamics_usergroupmember_create> against the userGroupMembers entity. See the example below.\n```json\nPOST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/users({userSecurityId})/userGroupMembers\n\nAuthorization: Bearer {token}\n{\n    \"code\": \"D365 EXT. ACCOUNTANT\",\n    \"companyName\" :\"CRONUS USA, Inc.\"\n}\n```\nTo retrieve the list of user groups issue a api/dynamics_usergroup_get. This returns the information that you need for the payload above.\nAssigning permission sets is identical to adding users to user groups. api/dynamics_permissionset_get returns information about the available permission sets. To assign a permissionSet issue a POST userPermission<api/dynamics_userpermission_create> as shown in the following example.\n```json\nPOST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/users({userSecurityId})/userPermissions\n\nAuthorization: Bearer {token}\n{\n    \"roleId\": \"SECURITY\"\n}\n```\nRemoving the permissionSet from the user is done by issuing a api/dynamics_userpermission_delete on the users entity.\n### Get new users from Office 365\nTo get new users from Office 365, two bound actions on the users endpoint can be used: Microsoft.NAV.getNewUsersFromOffice365 and Microsoft.NAV.getNewUsersFromOffice365Async. Both actions retrieve new users or new user information from the Office 365 portal but former one is designed for delegated admins and it runs synchronous and latter one schedules a background job, which makes it asynchronous. Microsoft.NAV.getNewUsersFromOffice365Async returns a link to the scheduled job where you can track the progress. You can also track the progress by issuing a api/dynamics_scheduledjob_get on the users entity. Existing, unchanged users won't be updated with these actions.\n> NOTE\n> The getNewUsersFromOffice365 and getNewUsersFromOffice365Async APIs aren't supported when using service-to-service (S2S) authentication. This operation requires that users are assigned the SUPER permission set in all companies, which can't be assigned to application users. See Using service-to-service (S2S) authentication<automation-apis-using-s2s-authentication>.\n## Inspect security and permissions\nUse the security and permission endpoints to inspect users, permission assignments, and object-level permissions. You access these endpoints through a company route, but their results aren't limited to the company in the route. They support GET requests and don't create, update, or delete security settings.\nEndpoint|Description\nusersPermissions|Gets users and their identity, state, license, and application information.\nuserPermissionSets|Gets permission set assignments for users, including the assignment type, company, security group, scope, and app.\naccessControls|Gets access control assignments that connect users, companies, and permission sets.\naggregatePermissionSets|Gets permission set identifiers, names, scopes, and originating apps.\nexpandedPermissionSets|Gets object-level read, insert, modify, delete, and execute permissions in each permission set.\nThe usersPermissions endpoint includes users with the `Full User`, `Limited User`, `Device Only User`, `External User`, `External Administrator`, or `External Accountant` license type. The aggregatePermissionSets endpoint excludes internal permission sets whose app name matches `*_Exclude_*`.\nFor example, to get users and their permission information, use the following request:\n```http\nGET https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/usersPermissions\nAuthorization: Bearer {token}\n```\nReplace usersPermissions with another endpoint from the preceding table to inspect other security and permission information.\n## Handling tenant extensions\nAdd-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 api/dynamics_extension_get. This returns the packageId needed for installing and uninstalling extensions.\n### Installing and uninstalling published add-on extensions\nThere are three bound actions available on the extensions endpoint: Microsoft.NAV.install, Microsoft.NAV.uninstall, and Microsoft.NAV.uninstallAndDeleteExtensionData.\nIssue a POST extension using the bound actions. See the example below, use the same syntax for the other bound actions.\n```json\nPOST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/extensions({packageId})/Microsoft.NAV.install\n\nAuthorization: Bearer {token}\n```\n### Unpublishing an uninstalled app\nOn the extensions endpoint, the Microsoft.NAV.unpublish is available to unpublish an uninstalled app.\nIssue a POST extension using the bound action. See the example below.\n```json\nPOST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/extensions({packageId})/Microsoft.NAV.unpublish\n\nAuthorization: Bearer {token}\n```\n> NOTE\n> The Microsoft.NAV.unpublish bound action is introduced in version 25.4. It's used for unpublishing an app, which isn't installed. You can choose to either uninstall and then unpublish the app, or you can install a new version of the app, which leaves the old app uninstalled, and then you can unpublish the app to remove it from the extensions list.\n### Upload and install a per-tenant extension\n> IMPORTANT\n> The recommended way to upload, install, and manage per-tenant extensions is now the Business Central Admin Center<tenant-admin-center-manage-apps> and its administration-center-api_app_management. The in-product Extension Management upload flow and the Automation API extensionUpload endpoint are deprecated and planned for removal in 2027 release wave 1. See ../upgrade/deprecated-features-platform.\nUse extensionUpload endpoint to upload and install the extension.\n> NOTE\n> Installing per-tenant extensions using Automation APIs is only possible in SaaS.\n### Insert extension upload\nFirst step is to create the configuration package, by issuing a POST extensionUpload<api/dynamics_extensionupload_create> in the Business Central tenant. Once the extension upload record is created, the extension can be uploaded. See the example below.\n```json\nPOST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/extensionUpload\n\nAuthorization: Bearer {token}\nContent-type: application/json\n{\n    \"schedule\":\"Current version\",\n    \"schemaSyncMode\": \"Add\"\n}\n```\n> NOTE\n> Schedule in the body can be \"Current version\", \"Next minor version\" or \"Next major version\".\n> NOTE\n> Schema Sync Mode in the body can be \"Add\" or \"Force Sync\".\n### Upload extension file\nOnce the extension upload record is created, an extension file can be uploaded with a PATCH extensionUpload<api/dynamics_extensionupload_update>. See the example below.\n```json\nPATCH https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/extensionUpload({extensionUploadId})/extensionContent\n\nAuthorization: Bearer {token}\nContent-type: application/octet-stream\nIf-Match: *\nBody: extension file.\n```\n### Install extension\nOnce extension file is uploaded, the extension needs to be installed by issuing a POST on the bound action Microsoft.NAV.upload<api/dynamics_extensionupload_create>.\n```json\nPOST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/extensionUpload({extensionUploadId})/Microsoft.NAV.upload\n\nAuthorization: Bearer {token}\n```\nUninstalling the extension can be done through the bound action Microsoft.NAV.uninstall<api/dynamics_extensionupload_create>, as with the add-on extensions. The bound action Microsoft.NAV.uninstallAndDeleteExtensionData can be used to delete the tables that contain data owned by the extension on uninstall. This action can't be undone.\n### Monitoring extension installation progress\nTo view ongoing extension installation status, issue api/dynamics_extensiondeploymentstatus_get as shown in the following example.\n```json\nGET https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/extensionDeploymentStatus\n```\n## Handling Feature Management\n### Get a list of available features\nTo view list of features available in feature management and their status issue a GET features<api/dynamics_featuremanagement_get>\n```json\nGET https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/features\n```\n### Activate a feature\nTo activate a feature, issue a POST activate<api/dynamics_activate_create> on the bound action Microsoft.NAV.activate against the specific feature resource. Use the {featureId} value from the GET features response.\n```json\nPOST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/features({featureId})/Microsoft.NAV.activate\nAuthorization: Bearer {token}\n{\n    \"updateInBackground\":false,\n    \"startDateTime\":\"2025-07-08T16:00:00Z\"\n}\n```\nIf successful, the request typically returns a \"200\" response. Use the GET features request to verify that the feature state has changed.\n### Deactivate a feature\nTo deactivate a feature, issue a POST deactivate<api/dynamics_deactivate_create> on the bound action Microsoft.NAV.deactivate against the specific feature resource.\n```json\nPOST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/features({featureId})/Microsoft.NAV.deactivate\nAuthorization: Bearer {token}\n```\nIf successful, the request typically returns a \"200\" response. Use the GET features request to verify that the feature state has changed.\n## Related information\nAutomation company<resources/dynamics_automationcompany>\nresources/dynamics_company\nConfiguration package<resources/dynamics_configurationpackage>\nresources/dynamics_extension\nExtension deployment status<resources/dynamics_extensiondeploymentstatus>\nExtension upload<resources/dynamics_extensionupload>\nPermission set<resources/dynamics_permissionset>\nresources/dynamics_profile\nScheduled job<resources/dynamics_scheduledjob>\nresources/dynamics_user\nUser group<resources/dynamics_usergroup>\nUser group member<resources/dynamics_usergroupmember>\nUser group permission<resources/dynamics_usergrouppermission>\nUser permission<resources/dynamics_userpermission>\nControl access to Business Central using security groups</ui-security-groups>"}