openapi: 3.0.3
info:
  title: Microsoft Dynamics 365 Business Central Accounts API
  description: The Microsoft Dynamics 365 Business Central API (v2.0) provides a RESTful interface for integrating with Business Central. It exposes standard business entities such as customers, vendors, items, sales orders, purchase orders, journals, and general ledger entries. The API uses OData v4 conventions and requires Microsoft Entra ID (Azure AD) authentication.
  version: '2.0'
  contact:
    name: Microsoft
    url: https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/
  license:
    name: Microsoft APIs Terms of Use
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
servers:
- url: https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environment}/api/v2.0
  description: Business Central Online (SaaS)
  variables:
    tenantId:
      default: common
      description: The Azure AD tenant ID or domain name.
    environment:
      default: production
      description: The Business Central environment name.
- url: https://{baseUrl}:{port}/{serverInstance}/api/v2.0
  description: Business Central On-Premises
  variables:
    baseUrl:
      default: localhost
    port:
      default: '7048'
    serverInstance:
      default: bc
security:
- oauth2: []
tags:
- name: Accounts
paths:
  /companies({companyId})/accounts:
    get:
      summary: Microsoft Dynamics List chart of accounts
      description: Returns a list of accounts from the chart of accounts.
      operationId: listAccounts
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/select'
      responses:
        '200':
          description: A list of accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
  /accounts:
    get:
      summary: Microsoft Dynamics List accounts
      description: Retrieves a collection of account records.
      operationId: listAccounts
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/orderby'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: A collection of accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account_2'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Microsoft Dynamics Create an account
      description: Creates a new account record.
      operationId: createAccount
      tags:
      - Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Account_2'
      responses:
        '204':
          description: Account created successfully.
          headers:
            OData-EntityId:
              description: URI of the created record.
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts({accountid}):
    get:
      summary: Microsoft Dynamics Get an account
      description: Retrieves a single account by ID.
      operationId: getAccount
      tags:
      - Accounts
      parameters:
      - name: accountid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: An account record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account_2'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      summary: Microsoft Dynamics Update an account
      description: Updates an existing account record.
      operationId: updateAccount
      tags:
      - Accounts
      parameters:
      - name: accountid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Account_2'
      responses:
        '204':
          description: Account updated successfully.
    delete:
      summary: Microsoft Dynamics Delete an account
      description: Deletes an account record.
      operationId: deleteAccount
      tags:
      - Accounts
      parameters:
      - name: accountid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Account deleted successfully.
components:
  responses:
    NotFound:
      description: The requested resource was not found.
    Unauthorized:
      description: Authentication required or token is invalid.
  parameters:
    ifMatch:
      name: If-Match
      in: header
      description: ETag value for optimistic concurrency.
      schema:
        type: string
    filter:
      name: $filter
      in: query
      description: OData filter expression.
      schema:
        type: string
    select:
      name: $select
      in: query
      description: Comma-separated list of properties to include.
      schema:
        type: string
    skip:
      name: $skip
      in: query
      description: Number of records to skip.
      schema:
        type: integer
    companyId:
      name: companyId
      in: path
      required: true
      description: The ID of the company.
      schema:
        type: string
        format: uuid
    top:
      name: $top
      in: query
      description: Maximum number of records to return.
      schema:
        type: integer
    expand:
      name: $expand
      in: query
      description: Related entities to expand inline.
      schema:
        type: string
    orderby:
      name: $orderby
      in: query
      description: Comma-separated list of properties to sort by.
      schema:
        type: string
  schemas:
    Account_2:
      type: object
      properties:
        accountid:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
        accountnumber:
          type: string
        description:
          type: string
        revenue:
          type: number
          format: decimal
        numberofemployees:
          type: integer
        industrycode:
          type: integer
        address1_line1:
          type: string
        address1_line2:
          type: string
        address1_city:
          type: string
        address1_stateorprovince:
          type: string
        address1_postalcode:
          type: string
        address1_country:
          type: string
        telephone1:
          type: string
        emailaddress1:
          type: string
        websiteurl:
          type: string
        statecode:
          type: integer
          description: 0 = Active, 1 = Inactive
        statuscode:
          type: integer
        createdon:
          type: string
          format: date-time
          readOnly: true
        modifiedon:
          type: string
          format: date-time
          readOnly: true
    Account:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        number:
          type: string
        displayName:
          type: string
        category:
          type: string
        subCategory:
          type: string
        blocked:
          type: boolean
        accountType:
          type: string
          enum:
          - Posting
          - Heading
          - Total
          - Begin-Total
          - End-Total
        lastModifiedDateTime:
          type: string
          format: date-time
          readOnly: true
  securitySchemes:
    oauth2:
      type: oauth2
      description: Microsoft Entra ID (Azure AD) OAuth 2.0 authentication.
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            https://api.businesscentral.dynamics.com/.default: Access Business Central API