openapi: 3.0.3
info:
  title: Microsoft Dynamics 365 Business Central Accounts Customers 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: Customers
paths:
  /companies({companyId})/customers:
    get:
      summary: Microsoft Dynamics List customers
      description: Returns a list of customer records.
      operationId: listCustomers
      tags:
      - Customers
      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 customers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Microsoft Dynamics Create a customer
      description: Creates a new customer record.
      operationId: createCustomer
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/companyId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Customer'
      responses:
        '201':
          description: The created customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /companies({companyId})/customers({customerId}):
    get:
      summary: Microsoft Dynamics Get a customer
      description: Returns a single customer by ID.
      operationId: getCustomer
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/companyId'
      - name: customerId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: A customer record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      summary: Microsoft Dynamics Update a customer
      description: Updates an existing customer record.
      operationId: updateCustomer
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/companyId'
      - name: customerId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Customer'
      responses:
        '200':
          description: The updated customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
    delete:
      summary: Microsoft Dynamics Delete a customer
      description: Deletes a customer record.
      operationId: deleteCustomer
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/companyId'
      - name: customerId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ifMatch'
      responses:
        '204':
          description: Successfully deleted.
  /Customers:
    get:
      summary: Microsoft Dynamics List customers
      description: Retrieves the collection of customer data entities.
      operationId: listCustomers
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/top_2'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/orderby'
      - $ref: '#/components/parameters/crossCompany'
      responses:
        '200':
          description: A collection of customer entities.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerEntity'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Microsoft Dynamics Create a customer
      description: Creates a new customer data entity.
      operationId: createCustomer
      tags:
      - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerEntity'
      responses:
        '201':
          description: The created customer entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerEntity'
components:
  responses:
    NotFound:
      description: The requested resource was not found.
    Unauthorized:
      description: Authentication required or token is invalid.
  parameters:
    top_2:
      name: $top
      in: query
      description: Maximum number of records to return (max 10000).
      schema:
        type: integer
    ifMatch:
      name: If-Match
      in: header
      description: ETag for optimistic concurrency control.
      required: true
      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
    crossCompany:
      name: cross-company
      in: query
      description: Set to true to retrieve data across all legal entities.
      schema:
        type: boolean
    companyId:
      name: companyId
      in: path
      required: true
      description: The ID of the company.
      schema:
        type: string
        format: uuid
    skip:
      name: $skip
      in: query
      description: Number of records to skip.
      schema:
        type: integer
    top:
      name: $top
      in: query
      description: Maximum number of records to return.
      schema:
        type: integer
    orderby:
      name: $orderby
      in: query
      description: Comma-separated list of properties to sort by.
      schema:
        type: string
  schemas:
    CustomerEntity:
      type: object
      properties:
        CustomerAccount:
          type: string
        CustomerGroupId:
          type: string
        OrganizationName:
          type: string
        AddressStreet:
          type: string
        AddressCity:
          type: string
        AddressState:
          type: string
        AddressZipCode:
          type: string
        AddressCountryRegionId:
          type: string
        PrimaryContactPhone:
          type: string
        PrimaryContactEmail:
          type: string
        SalesCurrencyCode:
          type: string
        CreditLimit:
          type: number
          format: decimal
        PaymentTermsName:
          type: string
        dataAreaId:
          type: string
    Customer:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        number:
          type: string
        displayName:
          type: string
        type:
          type: string
          enum:
          - Person
          - Company
        addressLine1:
          type: string
        addressLine2:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        postalCode:
          type: string
        phoneNumber:
          type: string
        email:
          type: string
        website:
          type: string
        taxRegistrationNumber:
          type: string
        currencyCode:
          type: string
        blocked:
          type: string
          enum:
          - ' '
          - Ship
          - Invoice
          - All
        balance:
          type: number
          format: decimal
          readOnly: true
        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