D365 Recurring Integration: Enqueue, Dequeue and Ack Explained
D365 finance and operations recurring integration enqueue dequeue API how to
Also searched as
- D365FO recurring data job REST API enqueue
- api/connector/enqueue activity id D365
- D365 dequeue ack recurring integration
- D365 import file via REST API data management
Short answer
Create a recurring data job on a data project, register an Entra ID application and authorize it in D365, then POST files to api/connector/enqueue/{activityId} to import, or GET api/connector/dequeue/{activityId} followed by an ack call to export. The job's activity ID in the URL ties your calls to the data project.
Applies to: Dynamics 365 Finance and Supply Chain Management (cloud). Recurring integrations REST connector with Entra ID (Azure AD) OAuth client credentials.
How to set up and call a recurring integration
- 1Register an application in Microsoft Entra ID with a client secret or certificate, and note the application (client) ID and tenant ID.
- 2In D365 open System administration > Setup > Microsoft Entra ID applications, add the client ID and map it to a user with the roles needed for the entities involved.
- 3Open Data management, create a data project and add the entity (for example Customers V3) with the source data format such as Package or CSV, and map the fields.
- 4In the data project select Create recurring data job. Name it, set Application ID to your client ID, tick the Enable data package or enable the import/export option, and set the processing recurrence if needed. Note the Activity ID (a GUID) shown after saving.
- 5Request an OAuth token using client credentials, with the environment URL as the resource, then call the connector endpoints using that Bearer token.
- 6To import, POST the file to the enqueue endpoint with the entity query parameter, for example https://yourenv.operations.dynamics.com/api/connector/enqueue/{activityId}?entity=Customers+V3, and read the returned message ID.
- 7To export, GET the dequeue endpoint, read the JSON with DownloadLocation and CorrelationId, download the file, then POST to the ack endpoint with the same correlation payload to mark it consumed.
- 8Check progress under Data management > Recurring data jobs > Manage messages, and on the job's execution history for errors on specific records.
How the connector works
Recurring integrations place messages in a queue in D365. The enqueue endpoint adds an inbound file as a message tied to the recurring job's activity ID. A batch process then picks messages up, imports them using the data project definition and updates the message status. For export, a batch job produces files that sit in the queue until an external caller dequeues them.
Because the process is queue based, a successful HTTP response from enqueue only means the message was accepted. It does not mean records were imported. Always check the message status and the execution log, and design your integration to correlate on the message ID the enqueue call returns.
The data project determines the format, entity and staging behaviour. If you send a file that does not match the entity's field mapping, the call can still be accepted and the failure shows up later in staging or execution details.
POST https://yourenv.operations.dynamics.com/api/connector/enqueue/{activityId}?entity=Customers+V3
Authorization: Bearer <token>
Content-Type: text/xml (or application/octet-stream for packages)
GET https://yourenv.operations.dynamics.com/api/connector/dequeue/{activityId}
Authorization: Bearer <token>
POST https://yourenv.operations.dynamics.com/api/connector/ack/{activityId}
Authorization: Bearer <token>
Body: the JSON returned by dequeue (CorrelationId, DownloadLocation, etc.)Authentication details
Use the client credentials flow against the Entra ID token endpoint with the resource set to your D365 base URL, with no trailing slash differences between what you request and what you call. A token issued for a different resource or tenant leads to 401 responses that look like a D365 problem but are an identity problem.
The application must also be listed in D365 under Microsoft Entra ID applications and mapped to a D365 user. A valid token for an application that D365 does not know yields an authorization failure. The mapped user needs security roles that grant access to the entities, because the integration runs as that user.
For production, prefer certificates or a managed secret store over long-lived client secrets, rotate them on a schedule, and keep separate app registrations for each environment so a test credential cannot reach production.
Troubleshooting failures
A 401 or 403 almost always points to token or mapping problems: wrong resource, expired secret, or an application not registered in D365. A 404 on enqueue often means the activity ID is wrong or belongs to another environment, for example after a sandbox refresh where recurring jobs were recreated or restored with different IDs.
Messages that sit in Queued do not move without batch. Check that the Process recurring job messages batch is running and not withheld. If messages move to Failed, open the execution details to see the entity-level error, which is usually a mapping or validation issue.
If throttling is the problem, you may see HTTP 429 responses on high-volume enqueue calls. Slow the sender, batch records into packages rather than posting thousands of single-record files, and see the OData throttling guidance for the underlying priority-based limits.
Common pitfalls
- !Treating a 200 response from enqueue as proof that records were imported.
- !Using the wrong resource URL when requesting the token, producing 401 errors.
- !Forgetting to register the application ID under Microsoft Entra ID applications in D365.
- !Not calling ack after dequeue, so the same export file is returned repeatedly.
- !Sending thousands of one-record files rather than a package, causing throttling.
- !Copying an activity ID between environments after a refresh without verifying it.
How an ERP-grounded AI assistant handles this
An assistant grounded in the environment, such as ERPray in read-only mode, can summarize the state of a recurring job: which messages are queued, failed or processed, which entity errors repeat, and whether the batch job that consumes them is running. It shows the queries it used, and any change to the job definition stays a human decision.
Frequently asked questions
What is the activity ID in the recurring integration URL?
It is the GUID assigned to the recurring data job when you save it. The connector uses it to route enqueue and dequeue calls to the right data project. You can see it on the recurring data job record in Data management.
Should I use recurring integrations or the data package API?
Recurring integrations suit scheduled, queue-based exchange where you want D365 to manage messages. The package REST API suits on-demand import and export with explicit execution calls. Choose based on whether you need a managed queue or direct control over each run.
Why does dequeue return nothing?
Nothing has been exported yet, or the export batch has not run. Check that the data project's recurring job is active and that its batch is processing. Previously dequeued messages not acknowledged may also be held until you call ack.
Can I use OData instead?
Yes, for small, synchronous reads and writes. For bulk loads, file-based data management is more efficient and avoids OData request throttling limits, at the cost of asynchronous processing.
Related
Fixing "Cannot create a record in (table). The record already exists" in D365 F&SCM data entity imports
This is the standard kernel duplicate-key exception, thrown when the Data Management Framework tries to insert a staging row into a target table whose unique or alternate key already matches an existing record. It almost always means the entity's insert-vs-update logic did not recognize the target row as an update, not that you have a true accidental duplicate in your source file.
How-toHandling OData 429 Too Many Requests throttling in D365 Finance and Operations
D365 F&SCM protects shared AOS capacity by throttling OData and custom service calls, returning HTTP 429 with a Retry-After header once a client sends too many requests too quickly. The durable fix is to honor Retry-After with backoff and redesign high-volume or frequent-polling integrations to use batching, business events, or Data management instead of tight request loops.
How-toHow to Refresh a Dynamics 365 F&SCM Sandbox From Production
In Lifecycle Services, open the target sandbox, choose Maintain > Move database > Refresh database, pick the production environment as the source and confirm. The copy replaces the sandbox AOS database, so you must then redo everything that is environment-specific: batch jobs, integration endpoints, email, print settings, users and Entra ID app registrations.
Error fixFixing "There are currently no batch servers available for processing" in D365 F&SCM
This message means the batch framework cannot find any AOS instance flagged as a batch server and available for the batch group the job is assigned to. The fix is almost always in server configuration (System administration > Servers) or batch group assignment, not in the batch job itself.
Error fixFixing "You do not have the following permissions on TableData (table): (permission)" in Business Central AL
This runtime error means the current user's assigned permission sets do not grant the required Insert, Modify, Delete, Read, or Execute right on that specific table. It is most common right after installing or updating a custom AL extension, because Business Central checks object-level permissions even for tables an extension owns.
Error fixFixing "The CIL object was not found" in Dynamics AX 2012
This error appears when the AOS tries to execute compiled CIL for a class or method that has not actually been regenerated since a code change was imported or edited, so the .NET runtime has nothing matching to run. The fix is a full compile followed by a full CIL generation and an AOS restart, not just a partial or incremental rebuild.
AI for ERPAI for Dynamics 365 Finance and Supply Chain beyond Copilot
AI for D365 Finance and Supply Chain beyond Microsoft Copilot: private LLM grounded on data entities and OData, on-prem-capable via Local Business Data.
Stuck on Microsoft Dynamics 365 Finance and Supply Chain Management?
Talk to engineers who work inside Microsoft Dynamics 365 Finance and Supply Chain Management every week, and who build private AI that answers these questions from your own ERP data.