Business Central API v2.0

openapi: 3.1.0
info:
  title: Dynamics 365 Business Central API v2.0
  description: >-
    Modern RESTful API for Microsoft Dynamics 365 Business Central, the cloud
    evolution of Dynamics NAV. Provides a comprehensive set of endpoints for
    managing customers, vendors, items, sales orders, purchase orders, accounts,
    journals, and other business entities. Supports OData query parameters for
    filtering, sorting, and pagination.
  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: Business Central API v2.0 Documentation
  url: https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/
servers:
- url: https://api.businesscentral.dynamics.com/v2.0/{environment}/api/v2.0
  description: Business Central Online (Common Endpoint)
  variables:
    environment:
      default: production
      description: The name of the Business Central environment
- url: https://{server}:{port}/{instance}/api/v2.0
  description: Business Central On-Premises
  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: Customers
  description: Manage customer records
- name: Vendors
  description: Manage vendor records
- name: Items
  description: Manage inventory items
- name: Sales Orders
  description: Manage sales orders and lines
- name: Purchase Orders
  description: Manage purchase orders and lines
- name: Accounts
  description: Manage general ledger accounts
- name: Journals
  description: Manage general journals and journal lines
- name: Companies
  description: Retrieve company information
- name: Employees
  description: Manage employee records
- name: Sales Invoices
  description: Manage sales invoices and lines
- name: Purchase Invoices
  description: Manage purchase invoices and lines
- name: Sales Quotes
  description: Manage sales quotes and lines
- name: Sales Credit Memos
  description: Manage sales credit memos
- name: Purchase Credit Memos
  description: Manage purchase credit memos
- name: Dimensions
  description: Manage dimensions and dimension values
- name: Currency
  description: Manage currencies and exchange rates
- name: Payment Terms
  description: Manage payment terms
- name: Payment Methods
  description: Manage payment methods
- name: Countries/Regions
  description: Manage country and region codes
- name: Item Categories
  description: Manage item categories
- name: Customer Payments
  description: Manage customer payment journals
- name: Vendor Payments
  description: Manage vendor payment journals
paths:
  /companies:
    get:
      summary: List Companies
      description: Returns a list of companies available in the Business Central tenant.
      operationId: listCompanies
      tags:
      - Companies
      parameters:
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/select'
      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
                      systemVersion: example_value
                      name: Example Title
                      displayName: example_value
                      businessProfileId: '500123'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/customers:
    get:
      summary: List Customers
      description: Returns a list of customer objects from the specified company.
      operationId: listCustomers
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/orderby'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: Successfully retrieved customers
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
              examples:
                Listcustomers200Example:
                  summary: Default listCustomers 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - '@odata.etag': example_value
                      id: abc123
                      number: example_value
                      displayName: example_value
                      type: Person
                      addressLine1: example_value
                      addressLine2: example_value
                      city: example_value
                      state: example_value
                      country: example_value
                      postalCode: example_value
                      phoneNumber: example_value
                      email: [email protected]
                      website: example_value
                      salespersonCode: example_value
                      balanceDue: 42.5
                      creditLimit: 42.5
                      taxLiable: true
                      taxAreaId: '500123'
                      taxAreaDisplayName: example_value
                      taxRegistrationNumber: example_value
                      currencyId: '500123'
                      currencyCode: example_value
                      paymentTermsId: '500123'
                      shipmentMethodId: '500123'
                      paymentMethodId: '500123'
                      blocked: ' '
                      lastModifiedDateTime: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: Create a Customer
      description: Creates a new customer object in the specified company.
      operationId: createCustomer
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/company_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerCreate'
            examples:
              CreatecustomerRequestExample:
                summary: Default createCustomer request
                x-microcks-default: true
                value:
                  number: example_value
                  displayName: example_value
                  type: Person
                  addressLine1: example_value
                  addressLine2: example_value
                  city: example_value
                  state: example_value
                  country: example_value
                  postalCode: example_value
                  phoneNumber: example_value
                  email: [email protected]
                  website: example_value
                  taxLiable: true
                  taxRegistrationNumber: example_value
                  currencyCode: example_value
                  blocked: ' '
      responses:
        '201':
          description: Customer created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              examples:
                Createcustomer201Example:
                  summary: Default createCustomer 201 response
                  x-microcks-default: true
                  value:
                    '@odata.etag': example_value
                    id: abc123
                    number: example_value
                    displayName: example_value
                    type: Person
                    addressLine1: example_value
                    addressLine2: example_value
                    city: example_value
                    state: example_value
                    country: example_value
                    postalCode: example_value
                    phoneNumber: example_value
                    email: [email protected]
                    website: example_value
                    salespersonCode: example_value
                    balanceDue: 42.5
                    creditLimit: 42.5
                    taxLiable: true
                    taxAreaId: '500123'
                    taxAreaDisplayName: example_value
                    taxRegistrationNumber: example_value
                    currencyId: '500123'
                    currencyCode: example_value
                    paymentTermsId: '500123'
                    shipmentMethodId: '500123'
                    paymentMethodId: '500123'
                    blocked: ' '
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/customers({customer_id}):
    get:
      summary: Get a Customer
      description: Retrieves a specific customer by ID.
      operationId: getCustomer
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/customer_id'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: Successfully retrieved customer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              examples:
                Getcustomer200Example:
                  summary: Default getCustomer 200 response
                  x-microcks-default: true
                  value:
                    '@odata.etag': example_value
                    id: abc123
                    number: example_value
                    displayName: example_value
                    type: Person
                    addressLine1: example_value
                    addressLine2: example_value
                    city: example_value
                    state: example_value
                    country: example_value
                    postalCode: example_value
                    phoneNumber: example_value
                    email: [email protected]
                    website: example_value
                    salespersonCode: example_value
                    balanceDue: 42.5
                    creditLimit: 42.5
                    taxLiable: true
                    taxAreaId: '500123'
                    taxAreaDisplayName: example_value
                    taxRegistrationNumber: example_value
                    currencyId: '500123'
                    currencyCode: example_value
                    paymentTermsId: '500123'
                    shipmentMethodId: '500123'
                    paymentMethodId: '500123'
                    blocked: ' '
                    lastModifiedDateTime: '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 Customer
      description: Updates an existing customer object.
      operationId: updateCustomer
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/customer_id'
      - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerUpdate'
            examples:
              UpdatecustomerRequestExample:
                summary: Default updateCustomer request
                x-microcks-default: true
                value:
                  displayName: example_value
                  type: Person
                  addressLine1: example_value
                  addressLine2: example_value
                  city: example_value
                  state: example_value
                  country: example_value
                  postalCode: example_value
                  phoneNumber: example_value
                  email: [email protected]
                  website: example_value
                  taxLiable: true
                  creditLimit: 42.5
                  blocked: ' '
      responses:
        '200':
          description: Customer updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              examples:
                Updatecustomer200Example:
                  summary: Default updateCustomer 200 response
                  x-microcks-default: true
                  value:
                    '@odata.etag': example_value
                    id: abc123
                    number: example_value
                    displayName: example_value
                    type: Person
                    addressLine1: example_value
                    addressLine2: example_value
                    city: example_value
                    state: example_value
                    country: example_value
                    postalCode: example_value
                    phoneNumber: example_value
                    email: [email protected]
                    website: example_value
                    salespersonCode: example_value
                    balanceDue: 42.5
                    creditLimit: 42.5
                    taxLiable: true
                    taxAreaId: '500123'
                    taxAreaDisplayName: example_value
                    taxRegistrationNumber: example_value
                    currencyId: '500123'
                    currencyCode: example_value
                    paymentTermsId: '500123'
                    shipmentMethodId: '500123'
                    paymentMethodId: '500123'
                    blocked: ' '
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: Delete a Customer
      description: Deletes a customer by ID.
      operationId: deleteCustomer
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/customer_id'
      responses:
        '204':
          description: Customer deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/vendors:
    get:
      summary: List Vendors
      description: Returns a list of vendor objects from the specified company.
      operationId: listVendors
      tags:
      - Vendors
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/orderby'
      - $ref: '#/components/parameters/select'
      responses:
        '200':
          description: Successfully retrieved vendors
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Vendor'
              examples:
                Listvendors200Example:
                  summary: Default listVendors 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - '@odata.etag': example_value
                      id: abc123
                      number: example_value
                      displayName: example_value
                      addressLine1: example_value
                      addressLine2: example_value
                      city: example_value
                      state: example_value
                      country: example_value
                      postalCode: example_value
                      phoneNumber: example_value
                      email: [email protected]
                      website: example_value
                      taxRegistrationNumber: example_value
                      currencyId: '500123'
                      currencyCode: example_value
                      paymentTermsId: '500123'
                      paymentMethodId: '500123'
                      taxLiable: true
                      blocked: ' '
                      balance: 42.5
                      lastModifiedDateTime: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: Create a Vendor
      description: Creates a new vendor object in the specified company.
      operationId: createVendor
      tags:
      - Vendors
      parameters:
      - $ref: '#/components/parameters/company_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorCreate'
            examples:
              CreatevendorRequestExample:
                summary: Default createVendor request
                x-microcks-default: true
                value:
                  number: example_value
                  displayName: example_value
                  addressLine1: example_value
                  addressLine2: example_value
                  city: example_value
                  state: example_value
                  country: example_value
                  postalCode: example_value
                  phoneNumber: example_value
                  email: [email protected]
                  website: example_value
                  taxRegistrationNumber: example_value
                  currencyCode: example_value
                  taxLiable: true
                  blocked: ' '
      responses:
        '201':
          description: Vendor created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vendor'
              examples:
                Createvendor201Example:
                  summary: Default createVendor 201 response
                  x-microcks-default: true
                  value:
                    '@odata.etag': example_value
                    id: abc123
                    number: example_value
                    displayName: example_value
                    addressLine1: example_value
                    addressLine2: example_value
                    city: example_value
                    state: example_value
                    country: example_value
                    postalCode: example_value
                    phoneNumber: example_value
                    email: [email protected]
                    website: example_value
                    taxRegistrationNumber: example_value
                    currencyId: '500123'
                    currencyCode: example_value
                    paymentTermsId: '500123'
                    paymentMethodId: '500123'
                    taxLiable: true
                    blocked: ' '
                    balance: 42.5
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/vendors({vendor_id}):
    get:
      summary: Get a Vendor
      description: Retrieves a specific vendor by ID.
      operationId: getVendor
      tags:
      - Vendors
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/vendor_id'
      - $ref: '#/components/parameters/select'
      responses:
        '200':
          description: Successfully retrieved vendor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vendor'
              examples:
                Getvendor200Example:
                  summary: Default getVendor 200 response
                  x-microcks-default: true
                  value:
                    '@odata.etag': example_value
                    id: abc123
                    number: example_value
                    displayName: example_value
                    addressLine1: example_value
                    addressLine2: example_value
                    city: example_value
                    state: example_value
                    country: example_value
                    postalCode: example_value
                    phoneNumber: example_value
                    email: [email protected]
                    website: example_value
                    taxRegistrationNumber: example_value
                    currencyId: '500123'
                    currencyCode: example_value
                    paymentTermsId: '500123'
                    paymentMethodId: '500123'
                    taxLiable: true
                    blocked: ' '
                    balance: 42.5
                    lastModifiedDateTime: '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 Vendor
      description: Updates an existing vendor object.
      operationId: updateVendor
      tags:
      - Vendors
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/vendor_id'
      - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorUpdate'
            examples:
              UpdatevendorRequestExample:
                summary: Default updateVendor request
                x-microcks-default: true
                value:
                  displayName: example_value
                  addressLine1: example_value
                  addressLine2: example_value
                  city: example_value
                  state: example_value
                  country: example_value
                  postalCode: example_value
                  phoneNumber: example_value
                  email: [email protected]
                  website: example_value
                  taxLiable: true
                  blocked: ' '
      responses:
        '200':
          description: Vendor updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vendor'
              examples:
                Updatevendor200Example:
                  summary: Default updateVendor 200 response
                  x-microcks-default: true
                  value:
                    '@odata.etag': example_value
                    id: abc123
                    number: example_value
                    displayName: example_value
                    addressLine1: example_value
                    addressLine2: example_value
                    city: example_value
                    state: example_value
                    country: example_value
                    postalCode: example_value
                    phoneNumber: example_value
                    email: [email protected]
                    website: example_value
                    taxRegistrationNumber: example_value
                    currencyId: '500123'
                    currencyCode: example_value
                    paymentTermsId: '500123'
                    paymentMethodId: '500123'
                    taxLiable: true
                    blocked: ' '
                    balance: 42.5
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: Delete a Vendor
      description: Deletes a vendor by ID.
      operationId: deleteVendor
      tags:
      - Vendors
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/vendor_id'
      responses:
        '204':
          description: Vendor deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/items:
    get:
      summary: List Items
      description: Returns a list of item objects from the specified company.
      operationId: listItems
      tags:
      - Items
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/orderby'
      - $ref: '#/components/parameters/select'
      responses:
        '200':
          description: Successfully retrieved items
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Item'
              examples:
                Listitems200Example:
                  summary: Default listItems 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - '@odata.etag': example_value
                      id: abc123
                      number: example_value
                      displayName: example_value
                      displayName2: example_value
                      type: Inventory
                      itemCategoryId: '500123'
                      itemCategoryCode: example_value
                      blocked: true
                      gtin: example_value
                      inventory: 42.5
                      unitPrice: 42.5
                      priceIncludesTax: true
                      unitCost: 42.5
                      taxGroupId: '500123'
                      taxGroupCode: example_value
                      baseUnitOfMeasureId: '500123'
                      baseUnitOfMeasureCode: example_value
                      generalProductPostingGroupId: '500123'
                      generalProductPostingGroupCode: example_value
                      inventoryPostingGroupId: '500123'
                      inventoryPostingGroupCode: example_value
                      lastModifiedDateTime: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: Create an Item
      description: Creates a new item object in the specified company.
      operationId: createItem
      tags:
      - Items
      parameters:
      - $ref: '#/components/parameters/company_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemCreate'
            examples:
              CreateitemRequestExample:
                summary: Default createItem request
                x-microcks-default: true
                value:
                  number: example_value
                  displayName: example_value
                  type: Inventory
                  itemCategoryCode: example_value
                  blocked: true
                  gtin: example_value
                  unitPrice: 42.5
                  unitCost: 42.5
                  taxGroupCode: example_value
                  baseUnitOfMeasureCode: example_value
      responses:
        '201':
          description: Item created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
              examples:
                Createitem201Example:
                  summary: Default createItem 201 response
                  x-microcks-default: true
                  value:
                    '@odata.etag': example_value
                    id: abc123
                    number: example_value
                    displayName: example_value
                    displayName2: example_value
                    type: Inventory
                    itemCategoryId: '500123'
                    itemCategoryCode: example_value
                    blocked: true
                    gtin: example_value
                    inventory: 42.5
                    unitPrice: 42.5
                    priceIncludesTax: true
                    unitCost: 42.5
                    taxGroupId: '500123'
                    taxGroupCode: example_value
                    baseUnitOfMeasureId: '500123'
                    baseUnitOfMeasureCode: example_value
                    generalProductPostingGroupId: '500123'
                    generalProductPostingGroupCode: example_value
                    inventoryPostingGroupId: '500123'
                    inventoryPostingGroupCode: example_value
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/items({item_id}):
    get:
      summary: Get an Item
      description: Retrieves a specific item by ID.
      operationId: getItem
      tags:
      - Items
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/item_id'
      - $ref: '#/components/parameters/select'
      responses:
        '200':
          description: Successfully retrieved item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
              examples:
                Getitem200Example:
                  summary: Default getItem 200 response
                  x-microcks-default: true
                  value:
                    '@odata.etag': example_value
                    id: abc123
                    number: example_value
                    displayName: example_value
                    displayName2: example_value
                    type: Inventory
                    itemCategoryId: '500123'
                    itemCategoryCode: example_value
                    blocked: true
                    gtin: example_value
                    inventory: 42.5
                    unitPrice: 42.5
            

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