Skip to main content
GOV.UK
Menu
HMRC Developer Hub
  • Documentation
  • Applications
  • Support
  • Service availability

GOV.UK uses cookies to make the site simpler. Find out more about cookies

  1. Home
  2. API Documentation
  3. Common Transit Convention Traders API v1.0 (Beta)
  • Register
  • Sign in
  • Overview
  • Versioning
  • Errors
  • Endpoints
 

This version is in beta - expect some breaking changes.

CTC Traders API

Available in SandboxYes
Sandbox base URLhttps://test-api.service.hmrc.gov.uk
Available in ProductionYes
Production base URLhttps://api.service.hmrc.gov.uk

Overview

This API will allow you to send departure and arrival movement notifications to the New Computerised Transit System (NCTS). It will also let you retrieve messages sent from the offices of departure and destination.

We have now released the API with working arrivals and departures endpoints. You can now run tests for GB movements in HMRC's sandbox environment.

  • Read our Roadmap to review our progress and see what you can test.
  • Read our step by step CTC Testing Guide to learn how to test. This signposts you to all the information and resources you will need.

Further details of 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.

Errors

Here is the list error codes that we will keep updating. We use standard HTTP status codes to show whether an API request has succeeded or not:

POST

400 BadRequest: XML has failed validation - see response body for details

401 Unauthorized: If client passes invalid auth credentials

403 Forbidden: If supplied auth token doesn't contain valid enrolment

404 Not Found: If no object with specified ID found in database

415 Unsupported Media Type: If the client specified an invalid Content-Type header

500 Internal Server Error: If exception in code occurs

501 Not Implemented: If user attempts to POST a message and the message type isn't currently supported

PUT

400 BadRequest: If XML message is invalid

401 Unauthorized: If client passes invalid auth credentials

403 Forbidden: If supplied auth token doesn't contain valid enrolment

404 Not Found: If no object with specified ID found in database

415 Unsupported Media Type: If the client specified an invalid Content-Type header

500 Internal Server Error: If exception in code occurs

GET

401 Unauthorized: If client passes invalid auth credentials

403 Forbidden: If supplied auth token doesn't contain valid enrolment

404 Not Found: If no object with specified ID found in database. Or if client passes in an Accept header which contains the wrong API version number. We have only released version 1.0 of the API

415 Unsupported Media Type: If Accept header contains invalid type

500 Internal Server Error: If exception in code occurs

Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.

Skip to main content

Endpoints

/customs/transits/movements/arrivals
Get all Movement Arrivals
GET

Get all Movement Arrivals.

Any Movement Arrivals more than 28 days old will have been archived along with their related messages. Archived movements will return an HTTP 404 Not Found status. You will only be able to retrieve these messages if you have the correct Economic Operator Registration and Identification (EORI) number for that Movement Arrival.

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

Request headers Table
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-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Response

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",
        "status": "ArrivalSubmitted",
        "_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",
        "status": "ArrivalSubmitted",
        "_links": {
          "self": {
            "href": "/customs/transits/movements/arrivals/2"
          },
          "messages": {
            "href": "/customs/transits/movements/arrivals/2/messages"
          }
        }
      }
    ]
  }
}

Error scenarios

Error scenarios table
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
Send an Arrival Notification message
POST

Send a notification to let the office at destination know that the goods have arrived.

This notification will be sent when the goods reach their final destination. It is also called an E_ARR_NOT (IE007).

The response will contain a URI and arrival ID for the Arrival Notification. This will allow you to get the message status.

If the user is not enrolled for an Economic Operator Registration and Identification number, they will receive an HTTP 403 Forbidden status.

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

Request headers Table
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.

Response

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}
Get a Movement Arrival for an arrival ID
GET

Get a specific Movement Arrival. Any Movement Arrivals more than 28 days old will be haven archived along with their related messages. Archived movements will return an HTTP 404 Not Found status.

You will only be able to retrieve these messages if you have the correct Economic Operator Registration and Identification (EORI) number for that Movement Arrival.

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

Path parameters table
Name Description
arrivalId
string
required

The arrival ID specifying the arrival to return

For example: 1

Request headers

Request headers Table
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-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Response

HTTP status: 200 (OK)

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

Error scenarios

Error scenarios table
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
Resubmit an Arrival Notification message
PUT

Resubmit an Arrival Notification to let the office at destination know that the goods have arrived. This message will be sent when the goods reach their final destination. It is also called an E_ARR_NOT (IE007).

The response will contain an arrival ID for the Arrival Notification. This will allow you to get the message status.

If the user is not enrolled for an Economic Operator Registration and Identification number, they will receive an HTTP 403 Forbidden status.

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

Path parameters table
Name Description
arrivalId
string
required

The arrival ID specifying the arrival to return

For example: 1

Request headers

Request headers Table
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.

Response

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 messages that relate to a Movement Arrival
GET

Get all the messages to do with a Movement Arrival. Any Movement Arrivals more than 28 days old will have been archived along with their related messages. Archived movements will return an HTTP 404 Not Found status.

You will only be able to retrieve these messages if you have the correct Economic Operator Registration and Identification (EORI) number for that Movement Arrival.

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

Path parameters table
Name Description
arrivalId
string
required

The arrival ID specifying the arrival to return

For example: 1

Request headers

Request headers Table
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-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Response

HTTP status: 200 (OK)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/arrivals/1/messages"
    }
  },
  "_embedded": {
    "messages": [
      {
        "_links": {
          "self": {
            "href": "/customs/transits/movements/arrivals/1/messages/1"
          },
          "arrival": {
            "href": "/customs/transits/movements/arrivals/1"
          }
        },
        "arrivalId": "1",
        "messageId": "1",
        "received": "2020-12-12T12:12:15",
        "messageType": "IE007",
        "body": "<CC007A>...</CC007A>"
      }
    ],
    "arrival": {
      "id": "1",
      "created": "2020-10-10T10:10:10",
      "updated": "2020-12-12T12:12:12",
      "movementReferenceNumber": "MRN",
      "status": "ArrivalSubmitted",
      "_links": {
        "self": {
          "href": "/customs/transits/movements/arrivals/1"
        },
        "messages": {
          "href": "/customs/transits/movements/arrivals/1/messages"
        }
      }
    }
  }
}

Error scenarios

Error scenarios table
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
Send a message related to an Movement Arrival
POST

Send a message to the office at destination. For example, an Unloading Remarks message, otherwise known as E_ULD_REM (IE044), to let them know that the goods have been unloaded.

The response will contain a URI and message ID for the message related to the Movement Arrival. This will allow you to get the message status.

If the user is not enrolled for an Economic Operator Registration and Identification number, they will receive an HTTP 403 Forbidden status.

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

Path parameters table
Name Description
arrivalId
string
required

The arrival ID specifying the arrival to return

For example: 1

Request headers

Request headers Table
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.

Response

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 message relating to a Movement Arrival and message ID
GET

Get all messages relating to a specific Movement Arrival and message ID. For example, this could include messages about route diversions or unloading permissions. Any Movement Arrivals more than 28 days old will have been archived along with their related messages. Archived movements will return an HTTP 404 Not Found status.

You will only be able to retrieve these messages if you have the correct Economic Operator Registration and Identification (EORI) number for that Movement Arrival.

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

Path parameters table
Name Description
arrivalId
string
required

The arrival ID specifying the arrival to return

For example: 1

messageId
string
required

The message ID specifying the message to return

For example: 1

Request headers

Request headers Table
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-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Response

HTTP status: 200 (OK)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/arrivals/1/messages/1"
    },
    "arrival": {
      "href": "/customs/transits/movements/arrivals/1"
    }
  },
  "arrivalId": "1",
  "messageId": "1",
  "received": "2020-10-10T10:10:10",
  "messageType": "IE007",
  "body": "<CC007A>...</CC007A>"
}

Error scenarios

Error scenarios table
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
Get all Movement Departures
GET

Get all Movement Departures sent to the office at departure within 28 days of the goods being released at their final destination. Any movement more than 28 days old will have been archived along with their related messages. Archived Movements will return an HTTP 404 Not Found status.

You will only be able to retrieve these messages if you have the correct Economic Operator Registration and Identification (EORI) number for that Movement Departure.

Note: The 'movementReferenceNumber' field will only be populated when an MRN is allocated.

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

Request headers Table
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-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Response

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",
        "status": "DepartureSubmitted",
        "_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",
        "status": "DepartureSubmitted",
        "_links": {
          "self": {
            "href": "/customs/transits/movements/departures/2"
          },
          "messages": {
            "href": "/customs/transits/movements/departures/2/messages"
          }
        }
      }
    ]
  }
}

Error scenarios

Error scenarios table
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
Send a Declaration Data message
POST

Send a Declaration Data message, to let the office at destination know that the goods are on their way. This notification will be sent when the goods leave the Office of Departure. It is also called an E_DEC_DAT (IE015).

The response will contain a URI and departure ID for the Declaration Data. This will allow you to retrieve the submission status.

If the user is not enrolled for an EORI number, they will receive an HTTP Forbidden Status.

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

Request headers Table
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.

Response

HTTP status: 202 (Accepted)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/departures/1"
    }
  },
  "departureId": "1",
  "messageType": "IE015",
  "body": "<CC015B>...</CC015B>"
}
Close section
/customs/transits/movements/departures/{departureId}
Get a Movement Departure for a departure ID
GET

Get a specific Movement Departure which was sent to the office at departure within 28 days of the goods being released at their final destination. Any Movements that are more than 28 days old will have been archived. Archived notifications will be return an HTTP 404 Not Found status.

You will only be able to retrieve these messages if you have the EORI number associated with the Movement Departure.

Note: The 'movementReferenceNumber' field will only be populated when an MRN is allocated.

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

Request headers Table
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-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Response

HTTP status: 200 (OK)

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

Error scenarios

Error scenarios table
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 messages relating to a Movement Departure
GET

Get all messages sent within 28 days of the goods being released relating to a Movement Departure. Any Movements that are more than 28 days old will have been archived. Archived notifications will be return an HTTP 404 Not Found status.

You will only be able to retrieve these messages if you have the EORI number associated with the Movement Departure.

Note: The 'movementReferenceNumber' field will only be populated when an MRN is allocated.

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

Request headers Table
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-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Response

HTTP status: 200 (OK)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/departures/1/messages"
    }
  },
  "_embedded": {
    "messages": [
      {
        "_links": {
          "self": {
            "href": "/customs/transits/movements/departures/1/messages/1"
          },
          "departure": {
            "href": "/customs/transits/movements/departures/1"
          }
        },
        "departureId": "1",
        "messageId": "1",
        "received": "2020-12-12T12:12:15",
        "messageType": "IE015",
        "body": "<CC015B>...</CC015B>"
      }
    ],
    "departure": {
      "id": "1",
      "created": "2020-10-10T10:10:10",
      "updated": "2020-12-12T12:12:12",
      "movementReferenceNumber": "MRN",
      "status": "DepartureSubmitted",
      "_links": {
        "self": {
          "href": "/customs/transits/movements/departures/1"
        },
        "messages": {
          "href": "/customs/transits/movements/departures/1/messages"
        }
      }
    }
  }
}

Error scenarios

Error scenarios table
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
Send a message related to a Movement Departure
POST

Send a message to the office at destination. For example, a Declaration Cancellation request message, otherwise known as E_DEC_CAN (IE014), to let them know that the trader wants to cancel their Declaration Data message (IE015).

The response will contain a URI and message ID for the message related to a Movement Departure. This will allow you to get the message status.

If the user is not enrolled for an Economic Operator Registration and Identification number, they will receive an HTTP

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

Request headers Table
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.

Response

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 message relating to a Movement Departure and message ID
GET

Get all messages relating to a specific Movement Departure and message ID. For example, this could include declaration rejected or Movement Reference Number (MRN) allocated messages. Any messages more than 28 days old will be archived. Archived notifications will be return an HTTP 404 Not Found status.

You will only be able to retrieve these messages if you have the EORI number associated with the Movement Departure.

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

Request headers Table
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-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Response

HTTP status: 200 (OK)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/departures/1/messages/1"
    },
    "departure": {
      "href": "/customs/transits/movements/departures/1"
    }
  },
  "departureId": "1",
  "messageId": "1",
  "received": "2020-10-10T10:10:10",
  "messageType": "IE015",
  "body": "<CC015B>...</CC015B>"
}

Error scenarios

Error scenarios table
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? Is this page not working properly?
  • Cookies
  • Privacy policy
  • Terms and conditions
  • Help using GOV.UK
  • Accessibility statement

Open Government Licence

All content is available under the Open Government Licence v3.0, except where otherwise stated

© Crown Copyright