This version is in beta - expect some breaking changes.

CTC Guarantee Balance API

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.

Skip to main content

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.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the common-transit-convention-guarantee-balance scope.

Request headers

Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Content-Type
required

Specifies the format of the request body, which must be JSON.

For example: 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 ^[A-Z]{3}$

HTTP status 202 (Accepted)

Response headers

Name Description
Location
required

The path of the newly created balance request

For example: /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.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the common-transit-convention-guarantee-balance scope.

Path parameters

Name Description
balanceId
string
required

The ID of the balance request to check.

For example: 22b9899e-24ee-48e6-a189-97d1f45391c4

Request headers

Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: 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

Skip to main content

Is this page not working properly? (opens in new tab)