openapi: 3.1.0
info:
  title: Business Central Administration Center Accounts Customers API
  description: REST API for programmatic administration of Dynamics 365 Business Central environments. Enables querying and managing production and sandbox environments, setting up administrative notifications, viewing tenant telemetry, managing apps, scheduling updates, and performing environment operations such as copy, rename, restore, and delete.
  version: '2.28'
  contact:
    name: Microsoft Dynamics Support
    email: bcsupport@microsoft.com
    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
servers:
- url: https://api.businesscentral.dynamics.com/admin/v2.28
  description: Business Central Administration Center
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Customers
  description: Manage customer records
paths:
  /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: user@example.com
                      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: user@example.com
                  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: user@example.com
                    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: user@example.com
                    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: user@example.com
                  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: user@example.com
                    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
components:
  parameters:
    ifMatch:
      name: If-Match
      in: header
      required: true
      description: ETag value for optimistic concurrency control
      schema:
        type: string
    filter:
      name: $filter
      in: query
      description: OData filter expression
      schema:
        type: string
    orderby:
      name: $orderby
      in: query
      description: OData order by expression
      schema:
        type: string
    expand:
      name: $expand
      in: query
      description: Related entities to expand inline
      schema:
        type: string
    skip:
      name: $skip
      in: query
      description: Number of items to skip
      schema:
        type: integer
        minimum: 0
    company_id:
      name: company_id
      in: path
      required: true
      description: The unique identifier of the company
      schema:
        type: string
        format: uuid
    select:
      name: $select
      in: query
      description: Comma-separated list of properties to include in the response
      schema:
        type: string
    top:
      name: $top
      in: query
      description: Maximum number of items to return
      schema:
        type: integer
        minimum: 0
    customer_id:
      name: customer_id
      in: path
      required: true
      description: The unique identifier of the customer
      schema:
        type: string
        format: uuid
  responses:
    Unauthorized:
      description: Unauthorized - authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request - invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A stable error code
            message:
              type: string
              description: A human-readable error message
          example: example_value
    Customer:
      type: object
      properties:
        '@odata.etag':
          type: string
          description: ETag for concurrency control
          example: example_value
        id:
          type: string
          format: uuid
          description: The unique identifier of the customer
          example: abc123
        number:
          type: string
          description: The customer number
          maxLength: 20
          example: example_value
        displayName:
          type: string
          description: The customer display name
          maxLength: 100
          example: example_value
        type:
          type: string
          description: The customer type
          enum:
          - Person
          - Company
          example: Person
        addressLine1:
          type: string
          description: First line of the address
          maxLength: 100
          example: example_value
        addressLine2:
          type: string
          description: Second line of the address
          maxLength: 50
          example: example_value
        city:
          type: string
          description: The city
          maxLength: 30
          example: example_value
        state:
          type: string
          description: The state or province code
          maxLength: 20
          example: example_value
        country:
          type: string
          description: The country/region code
          maxLength: 10
          example: example_value
        postalCode:
          type: string
          description: The postal code
          maxLength: 20
          example: example_value
        phoneNumber:
          type: string
          description: The phone number
          maxLength: 30
          example: example_value
        email:
          type: string
          description: The email address
          maxLength: 80
          example: user@example.com
        website:
          type: string
          description: The website URL
          maxLength: 80
          example: example_value
        salespersonCode:
          type: string
          description: The salesperson code
          maxLength: 20
          example: example_value
        balanceDue:
          type: number
          format: decimal
          description: The balance due from the customer
          readOnly: true
          example: 42.5
        creditLimit:
          type: number
          format: decimal
          description: The credit limit
          example: 42.5
        taxLiable:
          type: boolean
          description: Whether the customer is tax liable
          example: true
        taxAreaId:
          type: string
          format: uuid
          description: The tax area ID
          example: '500123'
        taxAreaDisplayName:
          type: string
          description: The tax area display name
          readOnly: true
          example: example_value
        taxRegistrationNumber:
          type: string
          description: The tax registration number
          maxLength: 20
          example: example_value
        currencyId:
          type: string
          format: uuid
          description: The currency ID
          example: '500123'
        currencyCode:
          type: string
          description: The currency code
          maxLength: 10
          example: example_value
        paymentTermsId:
          type: string
          format: uuid
          description: The payment terms ID
          example: '500123'
        shipmentMethodId:
          type: string
          format: uuid
          description: The shipment method ID
          example: '500123'
        paymentMethodId:
          type: string
          format: uuid
          description: The payment method ID
          example: '500123'
        blocked:
          type: string
          description: Whether the customer is blocked
          enum:
          - ' '
          - Ship
          - Invoice
          - All
          example: ' '
        lastModifiedDateTime:
          type: string
          format: date-time
          description: The date and time when the customer was last modified
          readOnly: true
          example: '2026-01-15T10:30:00Z'
    CustomerCreate:
      type: object
      required:
      - displayName
      properties:
        number:
          type: string
          maxLength: 20
          example: example_value
        displayName:
          type: string
          maxLength: 100
          example: example_value
        type:
          type: string
          enum:
          - Person
          - Company
          example: Person
        addressLine1:
          type: string
          maxLength: 100
          example: example_value
        addressLine2:
          type: string
          maxLength: 50
          example: example_value
        city:
          type: string
          maxLength: 30
          example: example_value
        state:
          type: string
          maxLength: 20
          example: example_value
        country:
          type: string
          maxLength: 10
          example: example_value
        postalCode:
          type: string
          maxLength: 20
          example: example_value
        phoneNumber:
          type: string
          maxLength: 30
          example: example_value
        email:
          type: string
          maxLength: 80
          example: user@example.com
        website:
          type: string
          maxLength: 80
          example: example_value
        taxLiable:
          type: boolean
          example: true
        taxRegistrationNumber:
          type: string
          maxLength: 20
          example: example_value
        currencyCode:
          type: string
          maxLength: 10
          example: example_value
        blocked:
          type: string
          enum:
          - ' '
          - Ship
          - Invoice
          - All
          example: ' '
    CustomerUpdate:
      type: object
      properties:
        displayName:
          type: string
          maxLength: 100
          example: example_value
        type:
          type: string
          enum:
          - Person
          - Company
          example: Person
        addressLine1:
          type: string
          maxLength: 100
          example: example_value
        addressLine2:
          type: string
          maxLength: 50
          example: example_value
        city:
          type: string
          maxLength: 30
          example: example_value
        state:
          type: string
          maxLength: 20
          example: example_value
        country:
          type: string
          maxLength: 10
          example: example_value
        postalCode:
          type: string
          maxLength: 20
          example: example_value
        phoneNumber:
          type: string
          maxLength: 30
          example: example_value
        email:
          type: string
          maxLength: 80
          example: user@example.com
        website:
          type: string
          maxLength: 80
          example: example_value
        taxLiable:
          type: boolean
          example: true
        creditLimit:
          type: number
          format: decimal
          example: 42.5
        blocked:
          type: string
          enum:
          - ' '
          - Ship
          - Invoice
          - All
          example: ' '
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication via Microsoft Entra ID
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
          scopes:
            https://api.businesscentral.dynamics.com/.default: Access Business Central Admin APIs
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
          scopes:
            https://api.businesscentral.dynamics.com/.default: Access Business Central Admin APIs
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Administration Center API Documentation
  url: https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/administration-center-api