Skip to main content

Developer set-up

To develop using these APIs you must:

  • be familiar with HTTP, RESTful services, XML and OAuth2
  • be registered as a developer on the HMRC Developer Hub
  • add at least one sandbox application on the Developer Hub

Each application you register will be assigned an HMRC ‘ApplicationId’.

You can view all the applications you have registered on the Developer Hub Applications page, where you can administer things like API subscriptions and application credentials.

Applications can be created in one of two possible environments:

  • sandbox environments - where you start development and testing of your software
  • production environment - when you are ready to go live, you can request ‘production credentials’ that will create you a new application (with a new ‘ApplicationId’) in the production environment

The main differences between these two environments are that in the sandbox environments you will create and use test users to call the endpoints, and the release versions of CDS APIs in the sandbox will generally be ahead of those in production.

More details about getting started using the sandbox environments.

The purpose of the CDS sandbox (also known as External Test) is to provide an HMRC platform for all external partners (CSPs, SWHs, express operators, and declarants) to complete their required assurance activities, so that they are confident in their readiness for migration to CDS.

The CDS External Test offering has two core services: Trade Test and Trader Dress Rehearsal, which are outlined below.

Trade Test

A functional test platform where third-party developers can assure their software integration against CDS APIs and a CDS back-end for all core declaration processes and notification types.

  • Test trader and account data
  • Process all declaration types and procedures
  • Integration testing for all APIs
  • Exports inventory linking
  • Simulated controls, quota, immediate payments services

Please note that the Trade Test environment is only able to support testing of ‘legitimate’ business volume scenarios and other automated declaration testing.

Business volume scenarios refer to genuine day-in-the-life-of tests which align to current trader patterns on CDS. For example, the arrival of a vessel at a port or a typical day’s submission of supplementary declarations. Full performance and throughput analysis (e.g. to break point) should not be conducted in Trade Test.

Trade Test is not a performance testing facility and has not been configured to the same standard as a Production environment. Any measured or perceived levels of system performance in Trade Test should not be expected to match the final Production system.

Trader Dress Rehearsal

A CDS-like service to support declarants in submitting all types of declarations, to expose all actors in the supply chain to declaration processing in CDS as part of their final assurance activity prior to submitting to CDS Live.

  • Live trader and account data
  • Process all declaration types and procedures
  • Integration testing for all APIs
  • Simulated controls, quota, immediate payments services

API subscription model

You must subscribe each application you register to the CDS APIs that they intend to use. Subscribing allows an application access to all of the endpoints of a particular API-version. An application may subscribe to as many APIs as required, but each ‘application => API-version’ pairing must have its own subscription enabled.

API access control

Some of the CDS APIs (and their documentation) are only accessible to applications that have been placed in the allow list for that API. If you cannot subscribe to or access the documentation of a particular API on the developer hub, please check with Software Developer Hub Support if your ‘ApplicationId’ needs to be added to the allow list for that API.

API versioning

When calling a CDS endpoint, you specify the version of the API you wish to use by specifying it in the ‘Accept’ request header of your request (see the specific API documentation for more details on request header values).

In the production environment, there is only one version available of each of the CDS APIs (version 1.0).

In the sandbox environments, however, there may be two versions available of a particular API: one for standard development (known as ‘Trade Test’); and another version (known as ‘Trader Dress Rehearsal’) that more closely mirrors the production environment.

Here is a breakdown of the CDS APIs, with the versions of each that relate to ‘Trade Test’ and ‘Trader Dress Rehearsal’ respectively:

API Service Trade Test Trader Dress Rehearsal
Customs Declarations API v 2.0 v 1.0
Customs Declarations Information API v 1.0 v 2.0
Customs Inventory Linking Exports API v 1.0 v 2.0
Customs Inventory Linking Imports API v 1.0 v 2.0


For your application to be able to call a particular version of an API, you must:

  • ensure that your application has access to it (by checking that the version is visible to you on the API’s documentation page)
  • subscribe your application to it (in addition to any other subscriptions you may already have for other versions)
  • modify your application’s ‘Accept’ request header value, when making a call to the API, to reflect the version you wish to use (see the specific API documentation for more details on request header values)

If a version of an API is not visible on the documentation page then you may need to request your application to be placed in the allow list by Software Developer Hub Support.

API rate limiting

Each software house should look to register a single application with HMRC. This application is used by us to identify the software house during the OAuth 2.0 grant flow, and then in subsequent per-user API calls. We limit the number of requests each application can make. This protects our backend service against excessive load and encourages real-time API calls over batch processing.

We set limits based on anticipated loads and peaks. Our standard limit is 3 requests per second per application, as set in the Reference Guide on HMRC’s Developer Hub, although CDS users are pre-approved for 8 requests per second and can obtain this limit by contacting Software Developer Hub Support. If you believe your application will sustain a traffic load above this value, then contact us to discuss it further.

If your software reaches the allocated limit then some of your requests will get a HTTP 429 response code. A 429 response should be treated in the same way that your application would handle any other transient HTTP response; by backing off temporarily, before attempting to make the request again.

In most cases, simply following software design best practices will deliver a good customer experience. API requests should not be unnecessarily batched, and rate-limited responses (HTTP 429) should be captured by the application and automatically retried without generating user errors. Retries should not be too quick (consider delaying the next attempt by a few seconds) and should include some randomisation, to minimise the risk of different application instances conflicting. Where an application instance is generating high volumes of API calls, the software design should consider periodically pausing or locally rate-limiting those API calls to minimise the potential for a spike in traffic from one instance impacting another.

Access to the Customs Inventory Linking Imports API is restricted to CSPs. If you are a CSP and cannot access the following API documentation, please contact SDST to request access:

Authentication

Declarants and authorized agents

The declarant authenticates directly with us using their Government Gateway account, and grants authority to your application for specific scopes.

Full details and examples can be found on the HMRC Developer Hub.

For information about authorisation-related errors that your application should handle, see the Reference Guide.

Community System Providers

Community System Providers (CSPs) will register privileged applications with HMRC.

The CSP system will supply data identifying each declarant during each interaction with CDS.

Error handling best practices

No system guarantees 100% error-free performance, and CDS is no different.

Services calling CDS need to be designed with failure in mind. There are several strategies to mitigate the errors that do occur.

5XX errors

When CDS returns a HTTP response code in the 5XX range, the recommended response is to retry. Typically, 500 or 503 response codes are the most likely to be received if there is an issue with CDS. The issue may be transient (hence the recommendation to retry). The one exception in this error range is when response code 501 (‘Not Implemented’) is returned. This indicates that the endpoint is incorrect. Retrying will not help in this situation. Instead, the URL should be corrected.

After multiple attempts, perhaps with an exponential backoff strategy, the expectation is that this will resolve the vast majority of errors. As an example, 3-5 retries over 1-2 minutes would be a reasonable retry strategy. Consideration should also be given to using the circuit-breaker pattern.

4XX errors

If a response code in the 4XX range is received, then the API consumer should examine the response payload for more detail on the error before attempting to retry. This error range usually indicates an error with the request. The request should be modified before attempting a retry. For example, a 400 response code (‘Bad Request’) accompanied by a payload response message stating “Payload is not valid according to schema” requires that the request payload is modified so that it validates against the CDS schemas before it is resent. Similarly, a 406 response code (‘Not Acceptable’) indicates that the ‘Accept’ header is missing or invalid. The request should be amended accordingly.

If you are receiving these errors consistently then you should report the problem via the normal routes.

403 errors

If you receive a response code 403 (‘Payload Forbidden’), accompanied by a payload response message stating “A firewall rejected the request”, do not retry entry. Report the problem via the normal routes.

There are many recommendations, and plenty of guidance is available on this topic. Some useful resources are listed below: