bc-api

---
name: bc-api
description: Communicate with Microsoft Dynamics 365 Business Central via its v2.0 REST API. Use when building integrations, querying BC data (customers, vendors, items, sales orders, GL entries), authenticating with OAuth2, or troubleshooting BC API calls.
license: MIT
---

# Business Central v2.0 API — Agent Skill

This skill teaches you how to interact with the Microsoft Dynamics 365 Business Central v2.0 REST API. It covers authentication, endpoint construction, CRUD operations, query parameters ($filter, $select, etc.), error handling, custom APIs, and webhooks. This is the modern JSON REST API — not the legacy OData or SOAP web service endpoints.

## Quick start — make your first BC API call

### 1. Get an access token

```bash
curl -X POST "https://login.microsoftonline.com/${TENANT_ID}/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=https://api.businesscentral.dynamics.com/.default" \
  -d "grant_type=client_credentials"
```

Save the `access_token` from the JSON response. Tokens are valid for ~1 hour.

### 2. List companies

```bash
curl -s "https://api.businesscentral.dynamics.com/v2.0/${TENANT_ID}/${ENVIRONMENT}/api/v2.0/companies" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"
```

### 3. Query an entity (e.g., customers)

```bash
curl -s "https://api.businesscentral.dynamics.com/v2.0/${TENANT_ID}/${ENVIRONMENT}/api/v2.0/companies(${COMPANY_ID})/customers?\$top=5&\$select=number,displayName,city" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"
```

## Base URL pattern

```
https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environment}/api/v2.0/
```

- `{tenantId}` — your Azure AD / Entra ID tenant GUID
- `{environment}` — BC environment name (e.g., `production`, `sandbox`)

All entity endpoints are scoped under a company:

```
.../api/v2.0/companies({companyId})/{entitySet}
```

## How to navigate this skill

| When you need...                          | Read this file                                      |
|-------------------------------------------|-----------------------------------------------------|
| API overview & base URL patterns          | [references/api-overview.md](references/api-overview.md) |
| OAuth2 authentication setup               | [references/authentication.md](references/authentication.md) |
| Entity endpoints, fields, CRUD examples   | [references/endpoints.md](references/endpoints.md) |
| Query params: $filter, $select, $expand, paging | [references/odata-query.md](references/odata-query.md) |
| Error codes and troubleshooting           | [references/error-handling.md](references/error-handling.md) |
| Custom API extensions                     | [references/custom-apis.md](references/custom-apis.md) |
| Webhook / subscription notifications      | [references/webhooks.md](references/webhooks.md) |
| Endpoint schema discovery for any BC API endpoint | [references/fetch-instructions.md](references/fetch-instructions.md) |
| Runnable test scripts (bash & PowerShell) | [scripts/README.md](scripts/README.md) |

## Opinionated guidance

### Auth token caching
- Cache the access token and reuse it until it expires. Parse `expires_in` (typically 3600 seconds) from the token response and refresh 5 minutes before expiry.
- For service-to-service (S2S) integrations, use `client_credentials` grant. No refresh tokens are issued — just request a new token when the old one expires.
- Never store tokens in source code or logs.

### Error handling
- Always check HTTP status codes first: 401 = re-authenticate, 404 = wrong URL/entity, 409 = concurrency conflict (re-read and retry with new `@odata.etag`).
- Parse the JSON error body for `error.code` and `error.message` — they contain actionable BC-specific details.
- For write operations (POST/PATCH/DELETE), always include the `If-Match` header with the entity's `@odata.etag` value to handle optimistic concurrency.
- Implement exponential backoff for 429 (rate limiting) and 503 (service unavailable) responses.

### Pagination
- BC uses server-driven paging. If the response contains `@odata.nextLink`, follow it to get the next page. Never assume all records are returned in a single response.
- Default page size is 20 records for API pages. Use `$top` to request up to 1000 records per page (the server may still enforce a lower limit).

### Common pitfalls
- Field names in OData queries are case-sensitive.
- Date filters use format `YYYY-MM-DD` (e.g., `$filter=postingDate ge 2024-01-01`).
- The `companies` endpoint is the only one that does NOT require a company ID scope.
- PATCH requires `Content-Type: application/json` and `If-Match: <etag>`.
- POST to create records does NOT use `If-Match`.