Business Central Automation API

openapi: 3.1.0
info:
  title: Business Central Automation API v2.0
  description: >-
    API for automating company setup and tenant management in Dynamics 365
    Business Central. Supports creating companies, installing and managing
    extensions, assigning permission sets to users, uploading and applying
    RapidStart packages, managing user groups and security groups, and
    activating features programmatically.
  version: '2.0'
  contact:
    name: Microsoft Dynamics Support
    email: [email protected]
    url: https://dynamics.microsoft.com/support/
  license:
    name: Microsoft APIs Terms of Use
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  termsOfService: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
externalDocs:
  description: Automation API Documentation
  url: https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/itpro-introduction-to-automation-apis
servers:
- url: https://api.businesscentral.dynamics.com/v2.0/{environment}/api/microsoft/automation/v2.0
  description: Business Central Online Automation API
  variables:
    environment:
      default: production
      description: The name of the Business Central environment
- url: https://{server}:{port}/{instance}/api/microsoft/automation/v2.0
  description: Business Central On-Premises Automation API
  variables:
    server:
      default: localhost
      description: The on-premises server hostname
    port:
      default: '7048'
      description: The OData services port
    instance:
      default: BC
      description: The Business Central server instance name
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Companies
  description: Manage automation companies
- name: Extensions
  description: Manage installed extensions
- name: Extension Upload
  description: Upload and install per-tenant extensions
- name: Extension Deployment Status
  description: Monitor extension installation progress
- name: Users
  description: Manage Business Central users
- name: User Groups
  description: Manage user groups (deprecated in v25, use security groups)
- name: Security Groups
  description: Manage security groups
- name: Permission Sets
  description: Manage permission sets and user permissions
- name: Configuration Packages
  description: Manage RapidStart configuration packages
- name: Features
  description: Manage feature flags
- name: Profiles
  description: Manage user profiles
- name: Scheduled Jobs
  description: View scheduled background jobs
paths:
  /companies:
    get:
      summary: List Companies
      description: Returns a list of companies available for automation.
      operationId: listCompanies
      tags:
      - Companies
      responses:
        '200':
          description: Successfully retrieved companies
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Company'
              examples:
                Listcompanies200Example:
                  summary: Default listCompanies 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - id: abc123
                      name: Example Title
                      displayName: example_value
                      businessProfileId: '500123'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/automationCompanies:
    get:
      summary: List Automation Companies
      description: Returns a list of automation company objects.
      operationId: listAutomationCompanies
      tags:
      - Companies
      parameters:
      - $ref: '#/components/parameters/company_id'
      responses:
        '200':
          description: Successfully retrieved automation companies
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/AutomationCompany'
              examples:
                Listautomationcompanies200Example:
                  summary: Default listAutomationCompanies 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - id: abc123
                      name: Example Title
                      displayName: example_value
                      businessProfileId: '500123'
                      evaluationCompany: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: Create a Company
      description: Creates a new company in the Business Central tenant.
      operationId: createAutomationCompany
      tags:
      - Companies
      parameters:
      - $ref: '#/components/parameters/company_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutomationCompanyCreate'
            examples:
              CreateautomationcompanyRequestExample:
                summary: Default createAutomationCompany request
                x-microcks-default: true
                value:
                  name: Example Title
                  displayName: example_value
                  businessProfileId: '500123'
      responses:
        '201':
          description: Company created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationCompany'
              examples:
                Createautomationcompany201Example:
                  summary: Default createAutomationCompany 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    displayName: example_value
                    businessProfileId: '500123'
                    evaluationCompany: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/automationCompanies({automationCompany_id}):
    get:
      summary: Get an Automation Company
      description: Retrieves a specific automation company by ID.
      operationId: getAutomationCompany
      tags:
      - Companies
      parameters:
      - $ref: '#/components/parameters/company_id'
      - name: automationCompany_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        example: '500123'
      responses:
        '200':
          description: Successfully retrieved automation company
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationCompany'
              examples:
                Getautomationcompany200Example:
                  summary: Default getAutomationCompany 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    displayName: example_value
                    businessProfileId: '500123'
                    evaluationCompany: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      summary: Update an Automation Company
      description: Updates properties of an automation company (e.g., rename).
      operationId: updateAutomationCompany
      tags:
      - Companies
      parameters:
      - $ref: '#/components/parameters/company_id'
      - name: automationCompany_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        example: '500123'
      - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutomationCompanyUpdate'
            examples:
              UpdateautomationcompanyRequestExample:
                summary: Default updateAutomationCompany request
                x-microcks-default: true
                value:
                  name: Example Title
                  displayName: example_value
      responses:
        '200':
          description: Company updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationCompany'
              examples:
                Updateautomationcompany200Example:
                  summary: Default updateAutomationCompany 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    displayName: example_value
                    businessProfileId: '500123'
                    evaluationCompany: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: Delete an Automation Company
      description: Deletes a company from the tenant.
      operationId: deleteAutomationCompany
      tags:
      - Companies
      parameters:
      - $ref: '#/components/parameters/company_id'
      - name: automationCompany_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        example: '500123'
      responses:
        '204':
          description: Company deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/extensions:
    get:
      summary: List Extensions
      description: Returns a list of extensions published to the tenant.
      operationId: listExtensions
      tags:
      - Extensions
      parameters:
      - $ref: '#/components/parameters/company_id'
      responses:
        '200':
          description: Successfully retrieved extensions
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Extension'
              examples:
                Listextensions200Example:
                  summary: Default listExtensions 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - id: abc123
                      packageId: '500123'
                      displayName: example_value
                      publisher: example_value
                      versionMajor: 10
                      versionMinor: 10
                      versionBuild: 10
                      versionRevision: 10
                      isInstalled: true
                      publishedAs: Global
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/extensions({extension_id})/Microsoft.NAV.install:
    post:
      summary: Install an Extension
      description: Installs a published extension on the tenant.
      operationId: installExtension
      tags:
      - Extensions
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/extension_id'
      responses:
        '204':
          description: Extension installation initiated
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/extensions({extension_id})/Microsoft.NAV.uninstall:
    post:
      summary: Uninstall an Extension
      description: Uninstalls an extension from the tenant.
      operationId: uninstallExtension
      tags:
      - Extensions
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/extension_id'
      responses:
        '204':
          description: Extension uninstallation initiated
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/extensions({extension_id})/Microsoft.NAV.uninstallAndDeleteExtensionData:
    post:
      summary: Uninstall and Delete Extension Data
      description: Uninstalls an extension and deletes all data owned by the extension. This action cannot be undone.
      operationId: uninstallAndDeleteExtensionData
      tags:
      - Extensions
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/extension_id'
      responses:
        '204':
          description: Extension uninstallation and data deletion initiated
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/extensions({extension_id})/Microsoft.NAV.unpublish:
    post:
      summary: Unpublish an Extension
      description: Unpublishes an uninstalled extension from the tenant.
      operationId: unpublishExtension
      tags:
      - Extensions
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/extension_id'
      responses:
        '204':
          description: Extension unpublished
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/extensionUpload:
    post:
      summary: Create Extension Upload Record
      description: Creates an extension upload record for uploading a per-tenant extension.
      operationId: createExtensionUpload
      tags:
      - Extension Upload
      parameters:
      - $ref: '#/components/parameters/company_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtensionUploadCreate'
            examples:
              CreateextensionuploadRequestExample:
                summary: Default createExtensionUpload request
                x-microcks-default: true
                value:
                  schedule: Current version
                  schemaSyncMode: Add
      responses:
        '201':
          description: Extension upload record created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensionUpload'
              examples:
                Createextensionupload201Example:
                  summary: Default createExtensionUpload 201 response
                  x-microcks-default: true
                  value:
                    systemId: '500123'
                    schedule: Current version
                    schemaSyncMode: Add
                    status: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/extensionUpload({extensionUpload_id})/extensionContent:
    patch:
      summary: Upload Extension File
      description: Uploads the extension file content to the extension upload record.
      operationId: uploadExtensionFile
      tags:
      - Extension Upload
      parameters:
      - $ref: '#/components/parameters/company_id'
      - name: extensionUpload_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        example: '500123'
      - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
            examples:
              UploadextensionfileRequestExample:
                summary: Default uploadExtensionFile request
                x-microcks-default: true
                value: example_value
      responses:
        '200':
          description: Extension file uploaded
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/extensionUpload({extensionUpload_id})/Microsoft.NAV.upload:
    post:
      summary: Install Uploaded Extension
      description: Triggers the installation of a previously uploaded per-tenant extension.
      operationId: installUploadedExtension
      tags:
      - Extension Upload
      parameters:
      - $ref: '#/components/parameters/company_id'
      - name: extensionUpload_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        example: '500123'
      responses:
        '204':
          description: Extension installation initiated
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/extensionDeploymentStatus:
    get:
      summary: List Extension Deployment Statuses
      description: Returns a list of ongoing extension deployment statuses.
      operationId: listExtensionDeploymentStatuses
      tags:
      - Extension Deployment Status
      parameters:
      - $ref: '#/components/parameters/company_id'
      responses:
        '200':
          description: Successfully retrieved deployment statuses
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExtensionDeploymentStatus'
              examples:
                Listextensiondeploymentstatuses200Example:
                  summary: Default listExtensionDeploymentStatuses 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - id: abc123
                      name: Example Title
                      publisher: example_value
                      operationType: example_value
                      status: Unknown
                      appVersion: example_value
                      startedOn: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/users:
    get:
      summary: List Users
      description: Returns a list of Business Central users.
      operationId: listUsers
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/company_id'
      responses:
        '200':
          description: Successfully retrieved users
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
              examples:
                Listusers200Example:
                  summary: Default listUsers 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - userSecurityId: '500123'
                      userName: example_value
                      displayName: example_value
                      state: Enabled
                      expiryDate: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/users({user_id}):
    get:
      summary: Get a User
      description: Retrieves a specific user by user security ID.
      operationId: getUser
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/user_id'
      responses:
        '200':
          description: Successfully retrieved user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                Getuser200Example:
                  summary: Default getUser 200 response
                  x-microcks-default: true
                  value:
                    userSecurityId: '500123'
                    userName: example_value
                    displayName: example_value
                    state: Enabled
                    expiryDate: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      summary: Update a User
      description: Updates properties of a Business Central user.
      operationId: updateUser
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/user_id'
      - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
            examples:
              UpdateuserRequestExample:
                summary: Default updateUser request
                x-microcks-default: true
                value:
                  state: Enabled
                  expiryDate: '2026-01-15T10:30:00Z'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                Updateuser200Example:
                  summary: Default updateUser 200 response
                  x-microcks-default: true
                  value:
                    userSecurityId: '500123'
                    userName: example_value
                    displayName: example_value
                    state: Enabled
                    expiryDate: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/users/Microsoft.NAV.getNewUsersFromOffice365:
    post:
      summary: Get New Users From Office 365
      description: >-
        Retrieves new users or updated user information from Office 365.
        Runs synchronously. Not supported with S2S authentication.
      operationId: getNewUsersFromOffice365
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/company_id'
      responses:
        '200':
          description: Users retrieved successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/users/Microsoft.NAV.getNewUsersFromOffice365Async:
    post:
      summary: Get New Users From Office 365 (async)
      description: >-
        Schedules a background job to retrieve new users from Office 365.
        Returns a link to the scheduled job for tracking progress. Not
        supported with S2S authentication.
      operationId: getNewUsersFromOffice365Async
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/company_id'
      responses:
        '202':
          description: Background job scheduled
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/users({user_id})/userPermissions:
    get:
      summary: List User Permissions
      description: Returns permission sets assigned to the user.
      operationId: listUserPermissions
      tags:
      - Permission Sets
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/user_id'
      responses:
        '200':
          description: Successfully retrieved user permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserPermission'
              examples:
                Listuserpermissions200Example:
                  summary: Default listUserPermissions 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - id: abc123
                      roleId: '500123'
                      displayName: example_value
                      company: example_value
                      scope: System
                      appId: '500123'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: Assign a Permission Set to a User
      description: Assigns a permission set to the specified user.
      operationId: createUserPermission
      tags:
      - Permission Sets
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/user_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - roleId
              properties:
                roleId:
                  type: string
                  description: The permission set role ID
            examples:
              CreateuserpermissionRequestExample:
                summary: Default createUserPermission request
                x-microcks-default: true
                value:
                  roleId: '500123'
      responses:
        '201':
          description: Permission set assigned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPermission'
              examples:
                Createuserpermission201Example:
                  summary: Default createUserPermission 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    roleId: '500123'
                    displayName: example_value
                    company: example_value
                    scope: System
                    appId: '500123'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/permissionSets:
    get:
      summary: List Permission Sets
      description: Returns a list of available permission sets.
      operationId: listPermissionSets
      tags:
      - Permission Sets
      parameters:
      - $ref: '#/components/parameters/company_id'
      responses:
        '200':
          description: Successfully retrieved permission sets
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/PermissionSet'
              examples:
                Listpermissionsets200Example:
                  summary: Default listPermissionSets 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - id: abc123
                      roleId: '500123'
                      displayName: example_value
                      scope: System
                      appId: '500123'
                      extensionName: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/securityGroups:
    get:
      summary: List Security Groups
      description: Returns a list of security groups.
      operationId: listSecurityGroups
      tags:
      - Security Groups
      parameters:
      - $ref: '#/components/parameters/company_id'
      responses:
        '200':
          description: Successfully retrieved security groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/SecurityGroup'
              examples:
                Listsecuritygroups200Example:
                  summary: Default listSecurityGroups 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - id: abc123
                      groupId: '500123'
                      code: example_value
                      displayName: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/configurationPackages:
    get:
      summary: List Configuration Packages
      description: Returns a list of RapidStart configuration packages.
      operationId: listConfigurationPackages
      tags:
      - Configuration Packages
      parameters:
      - $ref: '#/components/parameters/company_id'
      responses:
        '200':
          description: Successfully retrieved configuration packages
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConfigurationPackage'
              examples:
                Listconfigurationpackages200Example:
                  summary: Default listConfigurationPackages 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - id: abc123
                      code: example_value
                      packageName: example_value
                      languageId: '500123'
                      productVersion: example_value
                      processingOrder: 10
                      excludeConfigurationTables: true
                      numberOfTables: 10
                      numberOfRecords: 10
                      numberOfErrors: 10
                      importStatus: ' '
                      applyStatus: ' '
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: Create a Configuration Package
      description: Creates a new RapidStart configuration package record.
      operationId: createConfigurationPackage
      tags:
      - Configuration Packages
      parameters:
      - $ref: '#/components/parameters/company_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - code
              - packageName
              properties:
                code:
                  type: string
                  description: The configuration package code
                packageName:
                  type: string
                  description: The configuration package name
            examples:
              CreateconfigurationpackageRequestExample:
                summary: Default createConfigurationPackage request
                x-microcks-default: true
                value:
                  code: example_value
                  packageName: example_value
      responses:
        '201':
          description: Configuration package created
         

# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/navision/refs/heads/main/openapi/automation-api.yml