Dynamics 365 Dataverse API Capabilities

TL;DR

• Bottom line: Dataverse uses an OData v4.0 REST API (Web API v9.2) with two separate limit systems -- service protection limits (per-user, per-5-minute-window) and entitlement limits (per-license, per-24-hours). Both must be understood for successful integration. [src1, src7]
• Key limit: 6,000 requests per user per 5-minute sliding window per web server, with 20 minutes combined execution time in that same window. Entitlement: 40,000 requests/24h for Dynamics 365 Enterprise licenses. [src1, src2]
• Watch out for: Service protection limits and entitlement limits are evaluated independently -- batch operations ($batch) reduce request count but increase execution time, and each CRUD operation inside a batch still counts toward entitlement limits. [src1, src7]
• Best for: Real-time CRUD operations under 5,000 records, OData queries, change tracking for incremental sync, and batch operations up to 1,000 requests per $batch call. [src3, src4]
• Authentication: OAuth 2.0 via Microsoft Entra ID (Azure AD) -- use client credentials with certificate for server-to-server; authorization code flow for user-context operations. [src6]

System Profile

Microsoft Dataverse is the unified data platform underlying Dynamics 365 customer engagement apps (Sales, Customer Service, Field Service, Marketing) and the entire Power Platform (Power Apps, Power Automate, Power BI, Copilot Studio). The Web API implements OData v4.0 and is the primary integration surface for external applications. This card covers the Dataverse Web API as used by Dynamics 365 CE apps and Power Platform. It does NOT cover the Dynamics 365 Finance & Operations (F&O) data entities API.

API Surfaces & Capabilities

Rate Limits & Quotas

Service Protection Limits (Per-User, Per-Web-Server)

Returns HTTP 429 with Retry-After header. Plug-in execution does NOT count against service protection limits but adds to execution time of triggering request. [src1]

Entitlement Limits (Per-License, Per-24-Hours)

Multiple licenses stack. Each CRUD inside $batch counts individually toward entitlement. [src2]

Non-Licensed User Pool (Tenant-Level)

Per-Request Limits

Authentication

Authentication Gotchas

• Application user required: Client credentials flow requires creating an "application user" in Dataverse bound to the Azure AD app registration with a custom security role. [src6]
• ADAL is deprecated (EOL June 2022). All new integrations must use MSAL. [src6]
• Scope format: Public clients use <env-url>/user_impersonation; confidential clients use <env-url>/.default. Wrong scope = authentication failure. [src6]
• Client secrets have a 2-year maximum lifetime. Use certificates for long-running production integrations. [src6]

Constraints

• Service protection limits are per web server: The 6,000 request limit applies per server. With affinity cookies removed, requests distribute -- but this is not guaranteed. [src1]
• Batch operations do NOT bypass entitlement limits: Each CRUD in $batch counts individually toward the 24h entitlement quota. [src1, src7]
• Change tracking delta tokens expire in 7 days by default (configurable via ExpireChangeTrackingInDays). [src5]
• Change tracking does not support $filter, $orderby, $expand, or $top. [src5]
• Elastic tables: 500-row default query limit vs 5,000 for standard tables. [src3]
• Entitlement limits in transition period: Enforcement pending GA of usage reporting + 6 months. Build to official limits. [src2]
• Non-licensed user pool is shared across ALL application users in the tenant. [src2]
• Plug-in execution time adds to the triggering request's execution time budget. [src1]

Integration Pattern Decision Tree

START -- User needs to integrate with Dataverse
|-- What's the integration pattern?
|   |-- Real-time (individual records, <1s)
|   |   |-- <200 records/op? --> Web API single CRUD or Composite
|   |   |-- >200 records/op? --> Web API $batch with change sets (max 1,000)
|   |   +-- Need notifications? --> Webhooks or Service Bus integration
|   |-- Batch/Bulk (scheduled, high volume)
|   |   |-- <5,000 records? --> Web API $batch
|   |   |-- <100,000 records? --> SDK ExecuteMultiple with parallel threads
|   |   +-- >100,000 records? --> Azure Data Factory, SSIS, or Dataverse data export
|   |-- Event-driven (CDC, webhooks)
|   |   |-- Guaranteed delivery? --> Azure Service Bus + webhook registration
|   |   +-- Incremental sync? --> Change tracking (delta links)
|   +-- File-based (CSV/XML) --> Dataverse data import or Azure Data Factory
|-- Direction?
|   |-- Inbound --> check entitlement limits
|   |-- Outbound --> check service protection limits
|   +-- Bidirectional --> design conflict resolution FIRST
+-- Error tolerance?
    |-- Zero-loss --> $batch change sets + dead letter queue
    +-- Best-effort --> $batch + odata.continue-on-error + retry on 429

Quick Reference

Step-by-Step Integration Guide

1. Register Azure AD app and create application user

Register an app in Microsoft Entra ID with a client certificate or secret. Create an application user in Dataverse bound to that app registration with a custom security role. [src6]

# Get token using client credentials
curl -X POST "https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token" \
  -d "client_id={app_client_id}" \
  -d "scope=https://{org}.crm.dynamics.com/.default" \
  -d "client_secret={secret}" \
  -d "grant_type=client_credentials"

Verify: Response contains access_token field; decode JWT to confirm aud matches environment URL.

2. Execute a basic CRUD operation

Use the access token to create, read, update, or delete a record. [src3]

# Create an account
curl -X POST "https://{org}.crm.dynamics.com/api/data/v9.2/accounts" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "OData-MaxVersion: 4.0" -H "OData-Version: 4.0" \
  -d '{"name": "Contoso Inc", "telephone1": "555-0100"}'

Verify: HTTP 204 with OData-EntityId header.

3. Query with OData filters and pagination

Retrieve records using OData query options. [src3]

curl -X GET "https://{org}.crm.dynamics.com/api/data/v9.2/accounts?\$select=name,telephone1&\$filter=contains(name,'Contoso')&\$top=10" \
  -H "Authorization: Bearer {access_token}" \
  -H "OData-MaxVersion: 4.0" -H "OData-Version: 4.0"

Verify: HTTP 200 with value array. Check @odata.nextLink for pagination.

4. Batch operation with change set (atomic transaction)

Group write operations into an all-or-nothing transaction using change sets. [src4]

POST /api/data/v9.2/$batch HTTP/1.1
Content-Type: multipart/mixed; boundary="batch_unique123"

--batch_unique123
Content-Type: multipart/mixed; boundary="changeset_abc"

--changeset_abc
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 1

POST /api/data/v9.2/accounts HTTP/1.1
Content-Type: application/json; type=entry

{"name": "New Account"}
--changeset_abc
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 2

POST /api/data/v9.2/contacts HTTP/1.1
Content-Type: application/json; type=entry

{"firstname":"Jane","[email protected]":"$1"}
--changeset_abc--
--batch_unique123--

Verify: HTTP 200; each sub-response shows 204. Failure in any = full rollback.

5. Set up change tracking for incremental sync

Enable change tracking on the table, then use delta links to sync only changes. [src5]

# Initial request with change tracking
curl -X GET "https://{org}.crm.dynamics.com/api/data/v9.2/accounts?\$select=name" \
  -H "Authorization: Bearer {token}" \
  -H "Prefer: odata.track-changes" \
  -H "OData-MaxVersion: 4.0" -H "OData-Version: 4.0"
# Response includes @odata.deltaLink -- store for next sync

Verify: Response includes @odata.deltaLink. Subsequent calls return only changed/deleted records.

6. Implement retry logic for 429 responses

Handle service protection limits with exponential backoff using the Retry-After header. [src1]

import requests, time

def dataverse_request(url, headers, method="GET", json_body=None, max_retries=5):
    for attempt in range(max_retries):
        resp = getattr(requests, method.lower())(url, headers=headers, json=json_body)
        if resp.status_code == 429:
            wait = int(resp.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait)
            continue
        return resp
    raise Exception(f"Max retries exceeded for {url}")

Verify: On 429, function waits per Retry-After header and retries automatically.

Code Examples

Python: Paginated query with rate limit handling

# Input:  MSAL token, Dataverse org URL
# Output: All account records with pagination and 429 retry

from msal import ConfidentialClientApplication  # msal==1.28.0
import requests, time

app = ConfidentialClientApplication(
    "client-id", authority="https://login.microsoftonline.com/tenant-id",
    client_credential={"thumbprint": "THUMB", "private_key": open("key.pem").read()}
)
token = app.acquire_token_for_client(["https://org.crm.dynamics.com/.default"])
headers = {"Authorization": f"Bearer {token['access_token']}",
           "OData-MaxVersion": "4.0", "OData-Version": "4.0"}

def get_all(url):
    records = []
    while url:
        for attempt in range(5):
            r = requests.get(url, headers=headers)
            if r.status_code == 429:
                time.sleep(int(r.headers.get("Retry-After", 2**attempt)))
                continue
            r.raise_for_status(); break
        data = r.json()
        records.extend(data.get("value", []))
        url = data.get("@odata.nextLink")
    return records

JavaScript/Node.js: Batch upsert with change set

// Input:  Azure AD token, contact records array
// Output: Atomic batch upsert result

import { ClientCertificateCredential } from "@azure/identity"; // @azure/[email protected]
const cred = new ClientCertificateCredential("tenant", "client", "cert.pem");
const token = await cred.getToken("https://org.crm.dynamics.com/.default");

const batch = "batch_" + crypto.randomUUID();
const cs = "changeset_" + crypto.randomUUID();
let body = `--${batch}\r\nContent-Type: multipart/mixed; boundary="${cs}"\r\n\r\n`;
contacts.forEach((c, i) => {
  body += `--${cs}\r\nContent-Type: application/http\r\nContent-Transfer-Encoding: binary\r\nContent-ID: ${i+1}\r\n\r\n`;
  body += `PATCH /api/data/v9.2/contacts(${c.id}) HTTP/1.1\r\nContent-Type: application/json\r\n\r\n`;
  body += JSON.stringify(c) + "\r\n";
});
body += `--${cs}--\r\n--${batch}--\r\n`;

const resp = await fetch("https://org.crm.dynamics.com/api/data/v9.2/$batch", {
  method: "POST", body,
  headers: { Authorization: `Bearer ${token.token}`,
    "Content-Type": `multipart/mixed; boundary="${batch}"` }
});

cURL: Quick connectivity test

# Test auth and connectivity
curl -s "https://{org}.crm.dynamics.com/api/data/v9.2/WhoAmI" \
  -H "Authorization: Bearer {token}" \
  -H "OData-MaxVersion: 4.0" -H "OData-Version: 4.0" | python3 -m json.tool
# Expected: {"BusinessUnitId":"guid","UserId":"guid","OrganizationId":"guid"}

# Check rate limit headers (debug)
curl -v "https://{org}.crm.dynamics.com/api/data/v9.2/accounts?\$top=1" \
  -H "Authorization: Bearer {token}" 2>&1 | grep "x-ms-ratelimit"

Data Mapping

Dataverse-Specific Data Type Mapping

Data Type Gotchas

• Lookup fields have asymmetric read/write syntax: read returns _fieldname_value; write uses [email protected] with a URI. [src3]
• DateTime is always UTC in the API. Client applications must handle timezone conversion. [src3]
• OptionSet integer values for custom choices may differ between dev and prod if not solution-managed. [src3]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Affinity cookie removal: Rate limit headers reset across servers. Don't use x-ms-ratelimit-burst-remaining for flow control. [src1]
• Large batches hit execution time: A $batch with 1,000 ops may hit the 1,200s limit. Start with batch size 10. Fix: Gradually increase batch size while monitoring 429 responses. [src1]
• Delta token expiration: Change tracking tokens expire after 7 days. Fix: Implement fallback to full extraction with new initial delta. [src5]
• Plug-in recursion: Cascading plug-in triggers compound execution time against the original request. Fix: Implement recursion guards in plug-in code. [src1]
• OAuth token expiry mid-batch: Custom HTTP clients without MSAL refresh get 401 errors. Fix: Use MSAL AcquireTokenSilent or delegating handler pattern. [src6]

Anti-Patterns

Wrong: Sending individual requests for bulk operations

# BAD -- 10,000 individual POSTs will trigger service protection limits
for record in records:
    requests.post(f"{url}/api/data/v9.2/contacts", json=record, headers=headers)

Correct: Parallel requests with throttle-aware retry

# GOOD -- Parallel with concurrency limit + 429 handling
import concurrent.futures, time
def upsert(rec):
    for attempt in range(5):
        r = requests.patch(f"{url}/api/data/v9.2/contacts({rec['contactid']})",
                          json=rec, headers=headers)
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", 2**attempt)))
            continue
        return r.status_code
with concurrent.futures.ThreadPoolExecutor(max_workers=10) as ex:
    results = list(ex.map(upsert, records))

Wrong: Max-size $batch to minimize request count

# BAD -- 1,000-op batch exhausts execution time limit
batch_body = build_batch(all_1000_records)
requests.post(f"{url}/api/data/v9.2/$batch", data=batch_body, headers=headers)

Correct: Small batches with high parallelism

# GOOD -- Microsoft recommends small batches (10-50), increase gradually
for chunk in chunks(records, 10):
    batch_body = build_batch(chunk)
    resp = requests.post(f"{url}/api/data/v9.2/$batch", data=batch_body, headers=headers)
    if resp.status_code == 429:
        time.sleep(int(resp.headers.get("Retry-After", 5)))

Wrong: Polling all records to detect changes

# BAD -- Full query with modifiedon filter misses deletes, wastes quota
requests.get(f"{url}/api/data/v9.2/contacts?$filter=modifiedon gt {last_sync}")

Correct: Use change tracking with delta links

# GOOD -- Delta link returns only changed/deleted records
resp = requests.get(delta_link_url, headers=headers)
for item in resp.json().get("value", []):
    if "$deletedEntity" in item.get("@odata.context", ""):
        handle_delete(item["id"])
    else:
        handle_upsert(item)

Common Pitfalls

• Sandbox limits differ from production: Sandbox environments may have fewer web servers, lowering effective limits. Load-test against a similarly-configured sandbox. [src1]
• No odata.continue-on-error on $batch: Without change sets AND without this header, failure on request N stops processing of N+1 through 1000. Fix: Add Prefer: odata.continue-on-error header or use change sets. [src4]
• Relying on transition period limits: Current enforcement allows higher limits, but official 40K/day/user will be enforced after GA + 6 months. [src2]
• Not setting If-Match for concurrent updates: Without optimistic concurrency (ETag), last-write-wins silently overwrites changes. Fix: Send If-Match: W/"version" on PATCH. [src3]
• Using nested $expand with N:N relationships: OData doesn't support this. Fix: Use FetchXML for complex cross-entity joins. [src3]
• Confusing Dataverse CE API with F&O API: Dynamics 365 Finance & Operations has completely separate endpoints, rate limits, and auth. This card covers CE/Power Platform only. [src1]

Diagnostic Commands

# Check API connectivity and current user
curl -s "https://{org}.crm.dynamics.com/api/data/v9.2/WhoAmI" \
  -H "Authorization: Bearer {token}" -H "OData-MaxVersion: 4.0" -H "OData-Version: 4.0"

# Check remaining rate limit (response headers)
curl -v "https://{org}.crm.dynamics.com/api/data/v9.2/accounts?$top=1" \
  -H "Authorization: Bearer {token}" 2>&1 | grep "x-ms-ratelimit"

# Verify table change tracking status
curl -s "https://{org}.crm.dynamics.com/api/data/v9.2/EntityDefinitions(LogicalName='account')?$select=ChangeTrackingEnabled" \
  -H "Authorization: Bearer {token}" -H "OData-MaxVersion: 4.0" -H "OData-Version: 4.0"

# List all tables with change tracking enabled
curl -s "https://{org}.crm.dynamics.com/api/data/v9.2/EntityDefinitions?$select=LogicalName&$filter=ChangeTrackingEnabled eq true" \
  -H "Authorization: Bearer {token}" -H "OData-MaxVersion: 4.0" -H "OData-Version: 4.0"

# Check application user status
curl -s "https://{org}.crm.dynamics.com/api/data/v9.2/systemusers?$filter=applicationid eq {app_guid}&$select=fullname,isdisabled" \
  -H "Authorization: Bearer {token}" -H "OData-MaxVersion: 4.0" -H "OData-Version: 4.0"

Version History & Compatibility

OrganizationServiceProxy (SOAP) is deprecated in favor of ServiceClient. ADAL was end-of-life June 2022; use MSAL. [src3, src6]

When to Use / When Not to Use

Important Caveats

• Service protection limits are defaults and can vary. Trial environments get only one web server; production gets more based on licensed users. [src1]
• Entitlement limits are NOT strictly enforced yet (transition period). Build to official limits (40K/user/day for Enterprise) to avoid future disruption. [src2]
• Non-licensed user pool is shared across ALL application users in a tenant. A single misconfigured integration can starve all others. [src2]
• Batch operations save request count but not entitlement: each CRUD inside $batch counts toward 24h quota. [src1, src7]
• Rate limit numbers in this card are from January 2026 documentation. Microsoft may adjust values. Verify against current docs before production deployment. [src1, src2]