Skip to main content

Developer setup

To develop using CTC Guarantee Balance API v2.0, 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 API subscriptions and application credentials.

Applications can be created in one of 2 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 2 environments are that:

  • in the sandbox environment you will create and use test users to call the endpoints
  • the release version of an API in the sandbox will generally be ahead of the version of the API in production

The purpose of the sandbox (also known as External Test) is to provide an HMRC platform for all external partners to complete their required assurance activities so they are confident in their readiness for migration to NCTS phase 5.

For more information about using our sandbox environments, see Testing in the sandbox.

Trader Test

Trader Test is a functional test platform where you can assure your software integration. Trader Test simulates both the automated responses and also the real-life experience where NCTS support staff perform the tasks of Border Force personnel.

API subscription model

You must subscribe each application you register to CTC Guarantee Balance API v2.0. Subscribing allows an application access to all of the endpoints of the API.

API access control

CTC Guarantee Balance API v2.0 is a public API, so you should be able to gain access to it automatically and subscribe to it easily.

API versioning

For your application to be able to call a particular version of one of our APIs, you must:

  • ensure that your application has access to it (by checking that the version is visible at the top of 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 reference for more details about request header values)

For more information about versioning, see our Reference guide.

API rate limiting

Each software house should register a single application with HMRC. This application will be used to identify the software house during the OAuth 2.0 grant flow and will also be used in subsequent per user API calls. We limit the number of requests that 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. The rate limit of CTC Guarantee Balance API v2.0 is 1 request per minute per guarantee reference. It is not possible to request an increase in this rate limit.

If your software reaches the allocated limit, some of your requests will get a HTTP 429 response code. If your application receives a 429 response, it should back off temporarily before attempting to make the same 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 be automatically retried without generating user errors.

Retries should not be too quick (delay 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.

For more information about versioning, see our Reference guide.


You must use your Government Gateway account to authenticate directly with us. This grants authority to your application for specific scopes. We then issue an OAuth 2.0 access token that is specific to you. Your application passes the access token in subsequent API requests to user-restricted API endpoints. A declarant access token expires after 4 hours and will need to be refreshed.

For more information about user-restricted endpoints, see our Authorisation guide.

Error handling

No system guarantees 100% error-free performance, so services calling our APIs need to be designed with failure in mind. There are several strategies to mitigate the errors that do occur.

5XX errors

If an API returns an HTTP response code in the 5XX range, the recommended response is to retry. Typically, a 500 (Internal Server Error) or 503 (Service Unavailable) response will be returned if there is an issue with an API. The issue may be transient, hence the recommendation to retry. The one exception in this error range is when a 501 (Not Implemented) is returned. This indicates that the endpoint is incorrect. Retrying will not help in this situation. Instead, the URL should be checked and fixed.

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, the API consumer should examine the response payload for more detail on the error before attempting any retry. This error range usually indicates an error with the request. The request should be modified before attempting a retry.

For example, a 400 (Bad Request) with a payload response message stating ‘Payload is not valid according to schema’ should have its request payload modified so that it validates against the API schemas and then be resent. Similarly, a 406 (Not Acceptable) indicates that the Accept header is missing or invalid. The request should be amended accordingly.

If you are receiving these errors consistently, you should report the problem to the SDS Team.

Best practices recommendations

There are many best practices recommendations for handling API errors and exceptions, including the following: