Writing / Mastering Business Central APIs: Effortless CRUD with Postman Power-Ups

Unlocking Dynamics 365 Business Central APIs: Mastering Customer Endpoints with CRUD Examples

Introduction

In the world of ERP systems, Dynamics 365 Business Central stands out for its robust web services and APIs, enabling seamless integrations with custom apps, e-commerce platforms, or CRM tools. If you're a developer, IT pro, or business analyst, understanding the API endpoint structure is essential for automating tasks like managing customer data.

This guide dives deep into Business Central's API structure, focusing exclusively on the customers entity. We'll cover CRUD operations (Create, Read, Update, Delete) with practical examples, including code snippets and a ready-to-use Postman collection. By the end, you'll be equipped to build reliable integrations.

All examples are based on Microsoft's official documentation learn.microsoft.com. Let's get started!

Understanding the API Endpoint Structure

Business Central APIs follow a consistent URL pattern, making them predictable and easy to work with. The base structure is:

bash

https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environmentName}/api/{publisher}/{group}/{version}/companies({companyId})/{entityName}

{tenantId}: Your Azure Active Directory tenant ID (e.g., a GUID like 12345678-1234-1234-1234-1234567890ab).
{environmentName}: The environment, such as 'Production' or 'Sandbox'.
{publisher}/{group}/{version}: Typically 'microsoft/automation/v1.0' or 'v2.0' for standard APIs.
{companyId}: The GUID of your specific Business Central company.
{entityName}: The resource you're targeting, e.g., 'customers' for this guide.

Authentication requires OAuth 2.0 tokens—register an app in Azure AD and use client credentials flow to get a bearer token. Always include it in the Authorization header.

Pro Tip: Use OData query parameters for advanced filtering, like $filter=displayName eq 'Acme Corp' or $top=10 for pagination. Rate limits apply (e.g., 600 requests per minute), so handle errors gracefully.

Customer-Focused CRUD Examples

Let's apply this to the customers entity. These operations allow you to manage customer records, such as syncing from external systems or updating contact details.

1. GET: Retrieve Customers

Fetch a list of all customers or a single one by ID.

GET All Customers:

bash

GET https://api.businesscentral.dynamics.com/v2.0/{tenantId}/Production/api/v2.0/companies({companyId})/customers

Headers:

Authorization: Bearer {your-token}
Accept: application/json

Expected Response: A JSON array like:

json

{
  "value": [
    {
      "id": "guid-here",
      "number": "CUST001",
      "displayName": "Acme Corp",
      "email": "[email protected]"
    }
  ]
}

GET Single Customer (by ID):

bash

GET https://api.businesscentral.dynamics.com/v2.0/{tenantId}/Production/api/v2.0/companies({companyId})/customers({customerId})

2. POST: Create a New Customer

Add a new customer record.

bash

POST https://api.businesscentral.dynamics.com/v2.0/{tenantId}/Production/api/v2.0/companies({companyId})/customers

Headers:

Authorization: Bearer {your-token}
Content-Type: application/json

Body (JSON):

json

{
  "number": "CUST001",
  "displayName": "Acme Corp",
  "type": "Company",
  "email": "[email protected]",
  "currencyCode": "USD"
}

This is ideal for integrations like pulling leads from a CRM into Business Central.

3. PATCH: Update an Existing Customer

Modify specific fields of a customer (partial updates).

bash

PATCH https://api.businesscentral.dynamics.com/v2.0/{tenantId}/Production/api/v2.0/companies({companyId})/customers({customerId})

Headers:

Authorization: Bearer {your-token}
Content-Type: application/json

Body (JSON):

json

{
  "email": "[email protected]"
}

Use this for scenarios like updating addresses or payment terms.

4. DELETE: Remove a Customer

Permanently delete a customer (caution: this can't be undone and may affect linked data).

bash

DELETE https://api.businesscentral.dynamics.com/v2.0/{tenantId}/Production/api/v2.0/companies({companyId})/customers({customerId})

Headers:

Authorization: Bearer {your-token}

Hands-On Testing with Postman

To experiment without writing code, use this Postman collection. Copy the JSON below, save it as BusinessCentralCustomerAPI.json, and import it into Postman. Set the variables (e.g., in the collection's Variables tab) with your real values.

json

{
  "info": {
    "_postman_id": "business-central-customer-api-examples",
    "name": "Business Central Customer API Examples",
    "description": "Example CRUD calls for Dynamics 365 Business Central Customers API. Set variables: tenantId, environmentName, companyId, customerId, accessToken.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "GET All Customers",
      "request": {
        "method": "GET",
        "header": [
          { "key": "Authorization", "value": "Bearer {{accessToken}}", "type": "text" },
          { "key": "Accept", "value": "application/json", "type": "text" }
        ],
        "url": {
          "raw": "https://api.businesscentral.dynamics.com/v2.0/{{tenantId}}/{{environmentName}}/api/v2.0/companies({{companyId}})/customers",
          "protocol": "https",
          "host": ["api", "businesscentral", "dynamics", "com"],
          "path": ["v2.0", "{{tenantId}}", "{{environmentName}}", "api", "v2.0", "companies({{companyId}})", "customers"]
        }
      }
    },
    {
      "name": "GET Single Customer",
      "request": {
        "method": "GET",
        "header": [
          { "key": "Authorization", "value": "Bearer {{accessToken}}", "type": "text" },
          { "key": "Accept", "value": "application/json", "type": "text" }
        ],
        "url": {
          "raw": "https://api.businesscentral.dynamics.com/v2.0/{{tenantId}}/{{environmentName}}/api/v2.0/companies({{companyId}})/customers({{customerId}})",
          "protocol": "https",
          "host": ["api", "businesscentral", "dynamics", "com"],
          "path": ["v2.0", "{{tenantId}}", "{{environmentName}}", "api", "v2.0", "companies({{companyId}})", "customers({{customerId}})"]
        }
      }
    },
    {
      "name": "POST New Customer",
      "request": {
        "method": "POST",
        "header": [
          { "key": "Authorization", "value": "Bearer {{accessToken}}", "type": "text" },
          { "key": "Content-Type", "value": "application/json", "type": "text" }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"number\": \"CUST001\",\n  \"displayName\": \"Acme Corp\",\n  \"type\": \"Company\",\n  \"email\": \"[email protected]\",\n  \"currencyCode\": \"USD\"\n}"
        },
        "url": {
          "raw": "https://api.businesscentral.dynamics.com/v2.0/{{tenantId}}/{{environmentName}}/api/v2.0/companies({{companyId}})/customers",
          "protocol": "https",
          "host": ["api", "businesscentral", "dynamics", "com"],
          "path": ["v2.0", "{{tenantId}}", "{{environmentName}}", "api", "v2.0", "companies({{companyId}})", "customers"]
        }
      }
    },
    {
      "name": "PATCH Update Customer",
      "request": {
        "method": "PATCH",
        "header": [
          { "key": "Authorization", "value": "Bearer {{accessToken}}", "type": "text" },
          { "key": "Content-Type", "value": "application/json", "type": "text" }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"email\": \"[email protected]\"\n}"
        },
        "url": {
          "raw": "https://api.businesscentral.dynamics.com/v2.0/{{tenantId}}/{{environmentName}}/api/v2.0/companies({{companyId}})/customers({{customerId}})",
          "protocol": "https",
          "host": ["api", "businesscentral", "dynamics", "com"],
          "path": ["v2.0", "{{tenantId}}", "{{environmentName}}", "api", "v2.0", "companies({{companyId}})", "customers({{customerId}})"]
        }
      }
    },
    {
      "name": "DELETE Customer",
      "request": {
        "method": "DELETE",
        "header": [
          { "key": "Authorization", "value": "Bearer {{accessToken}}", "type": "text" }
        ],
        "url": {
          "raw": "https://api.businesscentral.dynamics.com/v2.0/{{tenantId}}/{{environmentName}}/api/v2.0/companies({{companyId}})/customers({{customerId}})",
          "protocol": "https",
          "host": ["api", "businesscentral", "dynamics", "com"],
          "path": ["v2.0", "{{tenantId}}", "{{environmentName}}", "api", "v2.0", "companies({{companyId}})", "customers({{customerId}})"]
        }
      }
    }
  ],
  "variable": [
    {"key": "tenantId", "value": "your-tenant-id-here"},
    {"key": "environmentName", "value": "Production"},
    {"key": "companyId", "value": "your-company-guid-here"},
    {"key": "customerId", "value": "your-customer-guid-here"},
    {"key": "accessToken", "value": "your-oauth-token-here"}
  ]
}

Best Practices and Common Challenges

Security: Never hardcode tokens—use secure storage.
Error Handling: Watch for 429 (rate limit) or 404 (not found) errors.
Testing: Start in a Sandbox environment to avoid disrupting production data.
Extensions: For custom fields, use AL extensions and bound actions.

Common challenges include authentication setup and handling large datasets—plan for batching if needed.

Conclusion

Mastering Business Central's customer APIs opens doors to powerful automations. Try the examples in Postman, and adapt them to your needs. Have questions or built something cool? Let me know!

Originally published on www.midego.net. Last updated: July 2025.