CTC Guarantee Balance API Service Guide
Useful CTC page links
CTC Guarantee Balance Testing Guide
CTC Guarantee Balance 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
- An IE34 request guarantee balance query is sent to NCTS and the XML is checked to ensure it’s valid.
- An IE917 rejection message is returned to the user if the XML is invalid.
- 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.
- If any of these are incorrect, an IE906 rejection message is returned to the user.
- 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.