CTC Guarantee Balance API
Date | Amount |
---|---|
Version and status | |
Available in Sandbox | Yes |
Sandbox base URL | https://test-api.service.hmrc.gov.uk |
Available in Production | Yes |
Production base URL | https://api.service.hmrc.gov.uk |
Overview
This CTC Guarantee Balance API will allow you to provide your users with up to date information from HMRC about their Guarantee Balance or balances. This helps your users plan ahead when organising goods transit movements into or out of the UK by telling your users how much of their Guarantee Balance they have left to use.
This CTC Guarantee Balance API works alongside the CTC Traders API which allows your software to send departure and arrival movement notifications to the New Computerised Transit System (NCTS).
You must note:
The Guarantee Balance API does not provide real time data on your users balance. It is possible that even a very short delay could coincide with events that could change their balance information. The balance responses could become out of date quickly if your users have a lot of transit movements progressing at the same time.
We have released the Guarantee Balance API to HMRC's sandbox environment. You can now run tests once you have finished your software development.
You should read:
- CTC Guarantee Balance Service Guide for how to integrate with this API
- Step by step Guide to Testing to learn how to test your software and ensure it is compatible with our CTC Guarantee Balance API
Further details about the User Restricted Authentication are given on the Authorisation page.
For more information about how to develop your own client applications, including example clients for this API, see Tutorials.
Versioning
When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.
Endpoints
/customs/guarantees/balances
Send a Balance Request
POST
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.
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.1.0+json
|
Content-Type
required
|
Specifies the format of the request body, which must be JSON. application/json
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the common-transit-convention-guarantee-balance scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Request
{ "taxIdentifier": "GB123456789012", "guaranteeReference": "20GB0000010000GX1", "accessCode": "ABC1" }
Name | Description |
---|---|
taxIdentifier
string
required
|
The trader identification number (TIN) of the principal on the guarantee. |
guaranteeReference
string
required
|
The guarantee reference number (GRN) of the guarantee. |
accessCode
string
required
|
The access code granting access to make use of the guarantee. |
Responses
HTTP status 200 (OK)
{ "response": { "balance": 12345678.9, "currency": "GBP" } }
Name | Description |
---|---|
_links
object
optional
|
An object containing links to other resources. |
_embedded
object
optional
|
An object containing embedded resources. |
response
object
required
|
A successful response from the guarantee management system |
balance
number
required
|
The remaining guarantee balance. |
currency
string
required
|
The alphanumeric 3-character ISO currency code of the currency in which the balance is held.
Must conform to the regular expression |
HTTP status 202 (Accepted)
Response headers
Name | Description |
---|---|
Location
required
|
The path of the newly created balance request /customs/guarantees/balances/22b9899e-24ee-48e6-a189-97d1f45391c4
|
See also fraud prevention.
{ "_links": { "self": { "href": "/customs/guarantees/balances/22b9899e-24ee-48e6-a189-97d1f45391c4" } }, "balanceId": "22b9899e-24ee-48e6-a189-97d1f45391c4" }
Name | Description |
---|---|
_links
object
required
|
An object containing links to other resources. |
_embedded
object
optional
|
An object containing embedded resources. |
balanceId
string
required
|
The ID of the balance request. |
HTTP status 400 (Bad Request)
{ "code": "FUNCTIONAL_ERROR", "message": "The request was rejected by the guarantee management system", "response": { "errors": [{ "errorType": 12, "errorPointer": "GRR(1).Guarantee reference number (GRN)" }] } }
Name | Description |
---|---|
_links
object
optional
|
An object containing links to other resources. |
_embedded
object
optional
|
An object containing embedded resources. |
code
required
|
Limited to the following possible values: FUNCTIONAL_ERROR
|
message
string
required
|
The description of the error. |
response
object
required
|
A functional error response from the guarantee management system |
errors
array
required
|
A functional error. |
errorType
number
required
|
The numeric error code of the functional error. |
errorPointer
string
required
|
The pointer string indicating the data item that was in error. |
errorReason
string
optional
|
The reason message indicating additional information about the cause of the error. |
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The request was rejected by the guarantee management system |
400 (Bad Request) |
FUNCTIONAL_ERROR |
The accept header is missing or invalid |
406 (Not Acceptable) |
ACCEPT_HEADER_INVALID |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Close Section
/customs/guarantees/balances/{balanceId}
Check the status of a Balance Request
GET
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.
Path parameters
Name | Description |
---|---|
balanceId
string
required
|
The ID of the balance request to check.
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.1.0+json
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the common-transit-convention-guarantee-balance scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
HTTP status 200 (OK) responses can be in the states of "Pending request", "Successful request", and "Failed request" as described below.
Pending request:
This is a pending request that has not yet received a response.
{ "_links": { "self": { "href": "/customs/guarantees/balances/22b9899e-24ee-48e6-a189-97d1f45391c4" } }, "request": { "balanceId": "22b9899e-24ee-48e6-a189-97d1f45391c4", "taxIdentifier": "GB123456789012", "guaranteeReference": "20GB0000010000GX1", "requestedAt": "2021-09-14T09:52:15Z" } }
Successful request:
This is a successful request that has received a balance response.
{ "_links": { "self": { "href": "/customs/guarantees/balances/22b9899e-24ee-48e6-a189-97d1f45391c4" } }, "request": { "balanceId": "22b9899e-24ee-48e6-a189-97d1f45391c4", "taxIdentifier": "GB123456789012", "guaranteeReference": "20GB0000010000GX1", "requestedAt": "2021-09-14T09:52:15Z", "completedAt": "2021-09-14T09:53:05Z", "response": { "status": "SUCCESS", "balance": 12345678.9, "currency": "EUR" } } }
Failed request:
This is a request that has received a functional error response.
{ "_links": { "self": { "href": "/customs/guarantees/balances/22b9899e-24ee-48e6-a189-97d1f45391c4" } }, "request": { "balanceId": "22b9899e-24ee-48e6-a189-97d1f45391c4", "taxIdentifier": "GB123456789012", "guaranteeReference": "20GB0000010000GX1", "requestedAt": "2021-09-14T09:52:15Z", "completedAt": "2021-09-14T09:53:05Z", "response": { "status": "FUNCTIONAL_ERROR", "errors": [{ "errorType": 12, "errorPointer": "GRR(1).Guarantee reference number (GRN)" }] } } }
Name | Description |
---|---|
_links
object
required
|
An object containing links to other resources. |
_embedded
object
optional
|
An object containing embedded resources. |
request
object
required
|
A request to the guarantee management system. |
balanceId
string
required
|
The ID of the balance request. |
taxIdentifier
string
required
|
The tax identifier of the holder of the guarantee. |
guaranteeReference
string
required
|
The guarantee reference number (GRN) of the guarantee. |
requestedAt
string
required
|
The timestamp when the balance request was created. |
completedAt
string
optional
|
The timestamp when the balance response was received. |
response
object
optional
|
The response from the guarantee management system. |
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
The balance request was not found |
404 (Not Found) |
NOT_FOUND |
The accept header is missing or invalid |
406 (Not Acceptable) |
ACCEPT_HEADER_INVALID |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Close Section