API Approach Document

Over the last few months,HMRC have been working to produce a stabilised view of their API design so that you can have confidence in what they are delivering and how the API target state will look. Below is an overview of the API Approach Document, as well as confirmation on the design principles that HMRC are implementing for these APIs and an FAQ.

 API Approach Document

 CDS 03 API Approach FAQ v1.0 190228 PS provides a high level view of the API target state and a more detailed view of the endpoints within the APIs that make up our target design. Please note that HMRC will also be issuing an updated version of the Digital Scope Document to reflect these updates.

 While you will notice that there are a number of endpoints still to be introduced, and a few indicated for deprecation, we have also spent a significant amount of time looking at our strategy for deprecating endpoints and communicating change. This has fed into the design principles which are outlined below.

 API Design Principles

HMRC would like to confirm the following design principles that we have implemented based on your feedback and to ensure that there is no impact on development against existing designs:

  • Changes to APIs: There are no plans to change the design for current APIs on the HMRC Developer Hub. If a requirement for a change is identified in the future, this will be communicated out in a timely manner to allow changes to be made.  
  • Backwards compatibility: To ensure there is no impact on development that is taking place against existing designs, we will ensure that any changes or enhancements will be backwards compatible where possible. Any enhancements that require a change which isn't backwards compatible will, where possible, be introduced as a separate endpoint or API. In cases where this is not possible, the change will be managed over extended timescales to allow for ample time for integration changes to be made.


 CDS 03 API Approach v1 2 190311 PC provides responses to some common questions on the API design and endpoints.

Please contact HMRC if you have any queries.

The API Approach Document will also be available on the HMRC Google Drive in the folder 03 Customs Declaration.

Back to news

We use cookies on this site to improve your experience. By continuing to browse the site you are agreeing to our use of cookies. You will only see this message once. Find out more