Using Delta Links With APIs

APPLIES TO: Business Central online

Delta links are opaque, service-generated links that the client uses to retrieve subsequent changes to a result.

The user can obtain a delta link from each entity API in the library by including the odata.track-changes preference in the header of the request. The response to the GET request returns a deltaLink parameter, providing an opaque URL.

On subsequent calls, the API consumer can use the deltaLink URL, which will provide the changes that have occurred in the data set since the initial request was made including the following points.

  • Any records that have not changed will exclude from the resulting response
  • Any added or updated entries appear as regular JSON objects with their current properties
  • Any records that have been removed will include in the response but represented only by their "id" and a @odata.context URL followed by a /$deletedEntity

Delta support limitations

  • The delta links apply to all entity APIs that include a persistent identifier, which is "id", and the deltaLink will not apply to APIs that do not have the ID property. For example, the report APIs like balanceSheet.
  • If a deltaLink is no longer valid, the service will respond with 410 Gone. The response should include a location header so that the client can use that to retrieve a new baseline set of results.
  • Not all entities in the API library support delta tokens. If a delta token is requested for an entity that does not support them, the service will respond with 500 Entity does not support delta requests.
  • The client must use the deltaLink URL as provided. The URL must not be modified either by parsing it or adding any additional query string parameters including changing the filters. The deltaLink and token are specific to the original query provided.

See Also

Developing Connect Apps for Dynamics 365 Business Central
Using Filtering With APIs
Tips for working with the APIs