CTC Traders 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

Use the CTC Traders API to:

  • send departure and arrival movement notifications to the New Computerised Transit System (NCTS)
  • retrieve messages sent from customs offices of departure and destination

The API endpoints relate only to Great Britain and Northern Ireland.

You can also use the HMRC sandbox environment to run tests for Great Britain and Northern Ireland transit movements.

Please note: This version of the API supports only NCTS Phase 4. Version 2.0 of the API supports NCTS Phase 5.

You should read:

  • Authorisation for information about user-restricted API authentication
  • Roadmap for information about CTC Traders API releases
  • Service Guide to learn how to use this version of the CTC Traders API with your software
  • Testing Guide to check that your software is compatible with this version of the CTC Traders API
  • Tutorials to learn how to develop your own client applications, including example clients, for the CTC Traders API

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.

Percent-encoding of parameters in request URLs

When writing code to use date filters in request URLs, you must always use percent-encoding to avoid getting 400 Bad Request errors. This is because some common characters used in dates and timestamps cannot be used in URLs.

Format

When formatting query parameters into a request URL for date and time filtering functionality, you must use only the ISO 8601 standard for the date and time. For example, the timestamp 2021-06-21T09:00+00:00 should be encoded as 2021-06-21T09%3A00%2B00%3A00. For more information about this, see our Reference guide.

You should also note the following:

  • some common data types described in our Reference guide contain characters that are not valid for use in URLs
  • some software libraries and frameworks do percent-encoding for you automatically

Examples

Below are examples in different programming languages.

Java

java.net.URLEncoder.encode("2021-04-30T16:08:31+00:00");

Python

from urllib.parse import quote

quote('2021-04-30T16:08:31+00:00')

C#

Uri.EscapeDataString("2021-04-30T16:08:31+00:00");

Find out more

For background information about percent-encoding, we recommend the following:

Push Pull notifications

You can use our Push-Pull-Notification Service (PPNS) to receive notifications of new messages from the NCTS as follows:

  • if your endpoint is hosted by Amazon Web Services (AWS), you must use either edge-optimised custom domain names or regional custom domain names
  • you will receive a push notification each time when there is a new message for you to read
  • for messages less than 100KB, a push notification will contain the message body
  • a push notification will have a field containing the message URI
  • you can use this URI to download the XML message from the CTC Traders API

Using this functionality means that you can avoid polling for new messages and thus save time and resources.

Errors

We use standard HTTP status codes to indicate whether an API request completed successfully.

The following list of standard error codes is subject to change.

Status code Description Explanation
400 Bad Request Invalid XML message (see response body for details).
401 Unauthorized Invalid authentication credentials.
403 Forbidden Authentication token doesn't contain a valid Economic Operators Registration and Identification (EORI) number.
404 Not Found No object with specified ID found in the NCTS database, or a client passed an Accept header that contains the wrong API version number.
415 Unsupported Media Type A client specified an invalid Content-Type header, or Accept header contains an invalid type.
500 Internal Server Error Code exception.
501 Not Implemented A user tried to POST a message but the message type isn't currently supported.

Some API endpoints have additional errors - see the Error scenarios of the relevant endpoints.

For more information about API errors, see our Reference guide.

Skip to main content

Endpoints

/customs/transits/movements/arrivals

Get all cached arrivals
GET

Retrieve all arrivals that have been updated within the past 31 days.

You can filter for arrivals updated after a specific date and time.

Movements older than 31 days and their related messages are archived and cannot be returned by the API.

Note: You can view a transit movement only if your Economic Operators Registration and Identification (EORI) number matches the EORI number that created the transit declaration for that movement. Your EORI number is part of the bearer token that you use for API authentication.

Authorisation

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

Query parameters

Name Description
updatedSince
datetime
optional

This is an optional query parameter that you can use to filter for arrivals updated after a specific date and time.

For example: 2021-06-21T09:00+00:00

Request headers

Name Description
Accept
required

Specifies the response format, which must be JSON, 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-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/arrivals"
    }
  },
  "_embedded": {
    "arrivals": [
      {
        "id": "1",
        "created": "2020-02-02T02:02:02",
        "updated": "2020-02-02T02:02:02",
        "movementReferenceNumber": "MRN",
        "_links": {
          "self": {
            "href": "/customs/transits/movements/arrivals/1"
          },
          "messages": {
            "href": "/customs/transits/movements/arrivals/1/messages"
          }
        }
      },
      {
        "id": "2",
        "created": "2020-02-04T02:02:02",
        "updated": "2020-02-04T02:02:02",
        "movementReferenceNumber": "MRN",
        "_links": {
          "self": {
            "href": "/customs/transits/movements/arrivals/2"
          },
          "messages": {
            "href": "/customs/transits/movements/arrivals/2/messages"
          }
        }
      }
    ],
    "retrievedArrivals": 2,
    "totalArrivals": 2
  }
}

Error scenarios

Scenario HTTP status Code

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/transits/movements/arrivals

Send an arrival notification message
POST

Notify the Customs Office of Destination that a transit movement has arrived at its final destination.

This request is also called an ‘Arrival Notification’ E_ARR_NOT (IE007) message.

A successful response will contain a URI and an arrival ID for the notification, which you can use to retrieve the message status.

It will also contain an embedded request ID, box ID and box name, which you can use to match this movement to any messages received from the Push Pull Notifications API.

Note: If an Economic Operators Registration and Identification (EORI) number has not been assigned to you, an HTTP 403 Forbidden error is returned.

Authorisation

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

Request headers

Name Description
Content-Type
required

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

For example: application/xml
Authorization
required
 An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 202 (Accepted)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/arrivals/1"
    }
  },
  "arrivalId": "1",
  "messageType": "IE007",
  "body": "<CC007A>...</CC007A>",
  "_embedded":
  {
    "notifications":{
      "boxId":"1234-5678-abcd-def",
      "requestId":"/customs/transits/movements/arrivals/1",
      "boxName":"customs/transits##1.0##notificationUrl"
    }
  }
}


Close Section
/customs/transits/movements/arrivals/{arrivalId}

Get a cached arrival for an arrival ID
GET

Retrieve a specific arrival that has been updated within the past 31 days.

Movements older than 31 days and their related messages are archived and cannot be returned by the API.

Note: You can view a transit movement only if your Economic Operators Registration and Identification (EORI) number matches the EORI number that created the transit declaration for that movement. Your EORI number is part of the bearer token that you use for API authentication.

Authorisation

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

Path parameters

Name Description
arrivalId
string
required

The arrival ID specifying the arrival to return.

For example: 1

Request headers

Name Description
Accept
required

Specifies the response format, which must be JSON, 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-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

{
  "id": "1",
  "created": "2020-10-10T10:10:10",
  "updated": "2020-12-12T12:12:12",
  "movementReferenceNumber": "MRN",
  "_links": {
    "self": {
      "href": "/customs/transits/movements/arrivals/1"
    },
    "messages": {
      "href": "/customs/transits/movements/arrivals/1/messages"
    }
  }
}

Error scenarios

Scenario HTTP status Code

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/transits/movements/arrivals/{arrivalId}

Resubmit an arrival notification message
PUT

Resend a notification to the Customs Office of Destination that a transit movement has arrived at its final destination.

This request is also called an ‘Arrival Notification’ E_ARR_NOT (IE007) message.

A successful response will contain a URI and an arrival ID for the notification, which you can use to retrieve the message status.

Note: If an Economic Operators Registration and Identification (EORI) number has not been assigned to you, an HTTP 403 Forbidden error is returned.

Authorisation

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

Path parameters

Name Description
arrivalId
string
required

The arrival ID specifying the arrival to return.

For example: 1

Request headers

Name Description
Content-Type
required

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

For example: application/xml
Authorization
required
 An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 202 (Accepted)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/arrivals/1"
    }
  },
  "arrivalId": "1",
  "messageType": "IE007",
  "body": "<CC007A>...</CC007A>"
}


Close Section
/customs/transits/movements/arrivals/{arrivalId}/messages

Get all cached messages related to an arrival
GET

Retrieve all messages related to a specific arrival that have been received within the past 31 days.

You can filter for arrivals received after a specific date and time.

Movements older than 31 days are archived, so any messages to related to them cannot be returned by the API.

Note: You can view a transit movement only if your Economic Operators Registration and Identification (EORI) number matches the EORI number that created the transit declaration for that movement. Your EORI number is part of the bearer token that you use for API authentication.

Request headers

Name Description
Accept
required

Specifies the response format, which must be JSON, 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-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.


Close Section
/customs/transits/movements/arrivals/{arrivalId}/messages

Send a message related to an arrival
POST

Send a message to the Customs Office of Destination about an arrival.

For example, if you are a Trader at Destination, you will send an ‘Unloading Remarks’ E_ULD_REM (IE044) message to the Customs Office of Destination indicating that unloading of the goods has been completed.

A successful response will contain a URI and an arrival ID for the message, which you can use to retrieve the message status.

Note: If an Economic Operators Registration and Identification (EORI) number has not been assigned to you, an HTTP 403 Forbidden error is returned.

Authorisation

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

Path parameters

Name Description
arrivalId
string
required

The arrival ID specifying the arrival to return.

For example: 1

Request headers

Name Description
Content-Type
required

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

For example: application/xml
Authorization
required
 An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 202 (Accepted)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/arrivals/1/messages/2"
    },
    "arrival": {
      "href": "/customs/transits/movements/arrivals/1"
    }
  },
  "arrivalId": "1",
  "messageId": "2",
  "messageType": "IE044",
  "body": "<CC044A>...</CC044A>"
}


Close Section
/customs/transits/movements/arrivals/{arrivalId}/messages/{messageId}

Get a cached message related to an arrival and message ID
GET

Retrieve all messages related to a specific arrival and message ID that have been received within the past 31 days.

For example, this could include messages about route diversions or unloading permissions.

Movements older than 31 days and their related messages are archived and cannot be returned by the API.

Note: You can view a transit movement only if your Economic Operators Registration and Identification (EORI) number matches the EORI number that created the transit declaration for that movement. Your EORI number is part of the bearer token that you use for API authentication.

Request headers

Name Description
Accept
required

Specifies the response format, which must be JSON, 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-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.


Close Section
/customs/transits/movements/departures

Get all cached departures
GET

Retrieve all departure declarations sent to the Customs Office of Departure within the past 31 days.

You can filter for departure declarations updated after a specific date and time.

Movements older than 31 days and their related messages are archived and cannot be returned by the API.

A successful response will include a Movement Reference Number (MRN) only after it has been allocated to a movement.

Note: You can view a transit movement only if your Economic Operators Registration and Identification (EORI) number matches the EORI number that created the transit declaration for that movement. Your EORI number is part of the bearer token that you use for API authentication.

Authorisation

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

Query parameters

Name Description
updatedSince
datetime
optional

This is an optional query parameter that you can use to filter for departure declarations updated after a specific date and time.

For example: 2021-06-21T09:00+00:00

Request headers

Name Description
Accept
required

Specifies the response format, which must be JSON, 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-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/departures"
    }
  },
  "_embedded": {
    "departures": [
      {
        "id": "1",
        "created": "2020-02-02T02:02:02",
        "updated": "2020-02-02T02:02:02",
        "movementReferenceNumber": "MRN",
        "_links": {
          "self": {
            "href": "/customs/transits/movements/departures/1"
          },
          "messages": {
            "href": "/customs/transits/movements/departures/1/messages"
          }
        }
      },
      {
        "id": "2",
        "created": "2020-02-04T02:02:02",
        "updated": "2020-02-04T02:02:02",
        "movementReferenceNumber": "MRN",
        "_links": {
          "self": {
            "href": "/customs/transits/movements/departures/2"
          },
          "messages": {
            "href": "/customs/transits/movements/departures/2/messages"
          }
        }
      }
    ],
    "retrievedDepartures": 2,
    "totalDepartures": 2
  }
}

Error scenarios

Scenario HTTP status Code

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/transits/movements/departures

Send a declaration data message
POST

Send a transit declaration to the Customs Office of Departure to notify it that you wish to carry out a transit operation.

This request is also called an ‘Declaration Data’ E_DEC_DAT (IE015) message.

A successful response will contain a URI and a departure ID for the notification, which you can use to retrieve the message status.

It will also contain an embedded request ID, box ID and box name, which you can use to match this movement to any messages received from the Push Pull Notifications API.

Note: If an Economic Operators Registration and Identification (EORI) number has not been assigned to you, an HTTP 403 Forbidden error is returned.

Authorisation

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

Request headers

Name Description
Content-Type
required

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

For example: application/xml
Authorization
required
 An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 202 (Accepted)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/departures/1"
    }
  },
  "departureId": "1",
  "messageType": "IE015",
  "body": "<CC015B>...</CC015B>",
  "_embedded":
  {
    "notifications":{
      "boxId":"1234-5678-abcd-def",
      "requestId":"/customs/transits/movements/departures/1",
      "boxName":"customs/transits##1.0##notificationUrl"
    }
  }
}


Close Section
/customs/transits/movements/departures/{departureId}

Get a cached departure for a departure ID
GET

Retrieve a specific departure declaration sent to the Customs Office of Departure within the past 31 days.

Movements older than 31 days and their related messages are archived and cannot be returned by the API.

A successful response will include a Movement Reference Number (MRN) only after it has been allocated to a movement.

Note: You can view a transit movement only if your Economic Operators Registration and Identification (EORI) number matches the EORI number that created the transit declaration for that movement. Your EORI number is part of the bearer token that you use for API authentication.

Authorisation

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

Request headers

Name Description
Accept
required

Specifies the response format, which must be JSON, 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-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

{
  "id": "1",
  "created": "2020-10-10T10:10:10",
  "updated": "2020-12-12T12:12:12",
  "movementReferenceNumber": "MRN",
  "_links": {
    "self": {
      "href": "/customs/transits/movements/departures/1"
    },
    "messages": {
      "href": "/customs/transits/movements/departures/1/messages"
    }
  }
}

Error scenarios

Scenario HTTP status Code

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/transits/movements/departures/{departureId}/messages

Get all cached messages related to a departure
GET

Retrieve all messages related to a specific departure declaration sent to the Customs Office of Departure within the past 31 days.

You can filter for departure declarations received after a specific date and time.

Movements older than 31 days are archived, so any messages to related to them cannot be returned by the API.

A successful response will include a Movement Reference Number (MRN) only after it has been allocated to a movement.

Note: You can view a transit movement only if your Economic Operators Registration and Identification (EORI) number matches the EORI number that created the transit declaration for that movement. Your EORI number is part of the bearer token that you use for API authentication.

Request headers

Name Description
Accept
required

Specifies the response format, which must be JSON, 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-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.


Close Section
/customs/transits/movements/departures/{departureId}/messages

Send a message related to a departure
POST

Send a message to the Customs Office of Departure about a departure.

For example, if you want to cancel a ‘Declaration Data’ E_DEC_DAT (IE015) message, you must send a ‘Declaration Invalidation Request’ E_DEC_INV (IE014) message to the Office of Departure.

A successful response will contain a URI and a message ID related to the departure, which you can use to retrieve the message status.

Note: If an Economic Operators Registration and Identification (EORI) number has not been assigned to you, an HTTP 403 Forbidden error is returned.

Authorisation

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

Request headers

Name Description
Content-Type
required

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

For example: application/xml
Authorization
required
 An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 202 (Accepted)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/departures/1/messages/2"
    },
    "departure": {
      "href": "/customs/transits/movements/departures/1"
    }
  },
  "departureId": "1",
  "messageId": "2",
  "messageType": "IE014",
  "body": "<CC014A>...</CC014A>"
}


Close Section
/customs/transits/movements/departures/{departureId}/messages/{messageId}

Get a cached message related to a departure and message ID
GET

Retrieve all messages related to a specific departure and message ID that have been received within the past 31 days.

For example, this could include ‘Declaration rejected’ or Movement Reference Number (MRN) allocated messages.

Movements older than 31 days and their related messages are archived and cannot be returned by the API.

Note: You can view a transit movement only if your Economic Operators Registration and Identification (EORI) number matches the EORI number that created the transit declaration for that movement. Your EORI number is part of the bearer token that you use for API authentication.

Request headers

Name Description
Accept
required

Specifies the response format, which must be JSON, 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-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.


Close Section
/customs/transits/movements/push-pull-notifications/box

Get box information for application
GET

Get box information for the application if there is a Push-Pull-Notification Service (PPNS) box.

Authorisation

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

Request headers

Name Description
Accept
required

Specifies the response format, which must be JSON, 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-traders scope.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Responses

HTTP status 200 (OK)

{
    "boxId": "5fb4b568-b5ff-4475-bd29-0a3e70abb6d6",
    "boxName": "customs/transits##1.0##notificationUrl",
    "_links": {
        "self": {
            "href": "/customs/transits/movements/push-pull-notifications/box"
        }
    }
}

Error scenarios

Scenario HTTP status Code

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)