Skip to main content

CTC Guarantee Balance API Service Guide

CTC Guarantee Balance Testing Guide

CTC Guarantee Balance API documentation

CTC Traders API documentation

Introduction

If you move goods between the UK and other countries who are part of the Common Transit Convention (CTC), your movements must have the appropriate guarantee funds to cover eventualities, such as: the loss of goods during transit.

Your goods can be delayed if your Guarantee Balance does not contain enough funds. This API has been provided so that you can check your balance and plan accordingly or increase it if you need to.

Before you start

You must understand:

  • the CTC Guarantee Balance API provides a snapshot of the guarantee state at the time the request is submitted

  • it is possible that even a very short delay could coincide with events that could change your balance information, such as the release of goods at the office of destination replenishing the guarantee amount locked against that movement

  • the balance responses could become out of date quickly if you have a lot of transit movements progressing at the same time

Authorisation

The endpoints in this API are user restricted. Further details about the User Restricted Authentication are given on the Developer Hub Authorisation page 4.

Process flow

The process of getting a Guarantee Balance is explained in this process flow chart:

Overview of Guarantee Balance process

Guarantee Balance process.

  1. An IE34 request guarantee balance query is sent to NCTS and the XML is checked to ensure it’s valid.
  2. An IE917 rejection message is returned to the user if the XML is invalid.
  3. Valid XML is checked by GMS to validate that the guarantee reference number (GRN), trader tax ID number (TIN) and guarantee access pin (PIN) are correct.
  4. If any of these are incorrect, an IE906 rejection message is returned to the user.
  5. A validated GMS check returns a successful IE37 receive guarantee balance message to the user.

How to use

To find out how much is left on a Guarantee Balance, you must provide:

  • the principal Economic Operators Registration and Identification (EORI) number for the guarantee

  • Access Code (a 4 digit alphanumeric pin that is not case sensitive)

  • Guarantee Reference Number (GRN)

You should note that Guarantee Balance information is only available for:

  • type 0: guarantee waiver
  • type 1: comprehensive guarantee
  • type 9: individual guarantee with multiple usage

Guarantee Balance information is not supported for:

  • type 2: individual guarantee (by guarantor)
  • type 4: individual guarantee in the form of vouchers

See the GOV.UK guidance for more detailed information about NCTS guarantees.

Endpoints

POST endpoint - used to initiate the balance request. You may receive a response immediately with a 200 OK or 400 Bad Request response, or a 202 Accepted response with a balance request ID.

GET endpoint - used to check the status of a balance request for which a response could not be provided immediately. You can use the balance request ID returned by the 202 Accepted response to call this endpoint.

Error codes

The following error codes are limited in their detail due to constraints of the NCTS system.

errorType errorPointer errorReason errorMessage
12 RC1.TIN Incorrect EORI Number
12 GRR(1).Guarantee reference number (GRN) Incorrect Guarantee Reference Number
12 GRR(1).ACC(1).Access code Incorrect Access Code
14 GRR(1).GQY(1).Query identifier R261 Unsupported Guarantee Type
12 GRR(1).OTG(1).TIN EORI and Guarantee Reference Number do not match
26 RC1.TIN Query limit for the EORI has been exceeded, or an unknown EORI has been used.

Note: There is a limit on the number of queries that can be made against an EORI number over a 24 hour period. An errorType 26 is returned if this limit is exceeded. The limit is currently set to 1000 in both Trader Test and Production environments; however, the Production limit may be subject to revision based upon usage.

API rate limit

The current API rate limit is 1 request per minute per guarantee reference. This improves the service provided to your software. You cannot request an increase to this rate limit.

Timing out period

Requests that take more than an hour to process will expire and will not be visible by the query endpoints. If this happens, you should start a new balance request. During normal service the response should take only seconds but if you are waiting longer then you should check the NCTS service availability.

JSON schema files and example requests

Detailed information for JSON schema files and example requests are available in the Guarantee Balance Testing Guide.

Get support

Before you get in touch, find out if there are any planned API downtime or technical issues by checking:

If you have specific questions about the CTC Guarantee Balance API, get in touch with our Software Developer Support Team.

You’ll get an initial response in 2 working days.

Email us your questions to SDSTeam@hmrc.gov.uk. We might ask for more detailed information when we respond.