Dynamics 365 Business Central APIs and Data Access Intent

One of the greatest advantages on using Dynamics 365 Business Central on a SaaS environment is certainly the availability of a read-only replica of the database. I’ve talked a lot about this feature in the past here on this blog but also on events, webcasts and courses.

In summary, objects like API pages, queries and reports can use the DataAccessIntent property in order to specify their data access intent. Possible values are:

  • ReadWrite: intent to read and modify records. This is executed on the primary database.
  • ReadOnly: intent to read records, without any modification. In this case the object runs on the read-only replica of the database.

The ReadOnly setting works as a hint for the server to route the connection to a secondary (read-only) replica, if available. When a workload is executed against the replica, insert/delete/modify operations aren’t possible. If any of these operations are executed against the replica, an exception is thrown at runtime.

By using the read-only replica you can off-load the production database and then execute your queries and your statistical reports without impacting production performances.

Please remember (as explained in my old post) that you can override the DataAccessIntent property from the client by using the Database Access Intent List page:

What’s the news then?

Starting from Dynamics 365 Business Central 2021 Wave 2 release (version 19) all API calls can specify the data access intent directly from the OData call.

Now, by specifying the HTTP request header Data-Access-Intent, it’s possible to override the data access intent of the API page or query that has been defined with a DataAccessIntent property.

As an example, if you want to retrieve the Customers by using APIs and you want to read them from the read-only replica of the database, you can now do the following:

Please remember the following rules:

  • When you perform an API call with the Data-Access-Intent request header specified, the value of the DataAccessIntent property defined on the object (if present) is ignored.
  • The settings specified in the Database Access Intent List page have higher priority then the value specified in the request header (they wins).
  • If you perform an API call that requires data modification (like POST, PATCH, DELETE) and you specify Datas-Access-Intent: ReadOnly in the request header, an error is thrown.

Regarding to this last point, if we try to insert a Customer record and we specify the Data-Access-Intent: ReadOnly header parameter:

we’ll receive the following error:

My suggestion is to start using the HTTP request header Data-Access-Intent: ReadOnly as much as possible on your API queries for your external integrations. You will gain on performances of the entire system and all integrations that requires reading data will have no impact on your production workloads.


  1. Hi there,

    Thanks for the informative doc – nice to see.
    Interestingly when we try this with the purchaseOrders API endpoint (GET /purchaseOrders) we get the error thrown “BadRequest_IncompatibleDataAccessIntent. Cannot modify a record. Current connection intent is Read-Only.”

    Have you seen this appear for certain endpoints?
    Perhaps with conflicting permission set configuration


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.