• Register
• Sign in

 

This version is in alpha - You will not be able to subscribe to this API.

CTC Traders API

Available in Sandbox	No
Available in Production	No

Overview

This API allows you to send departure and arrival movement notifications to the New Computerised Transit System (NCTS). You can also retrieve messages sent from the Office of Departure and Office of Destination.

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

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

• 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
• 400 to 499 if it failed because of a client error by your application
• 500 to 599 if it failed because of an error on our server

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

Back to top

Endpoints

/customs/transits/movements/arrivals

Pull all arrival notifications

GET

Pull all arrival messages sent to the Office of Destination within 21 days ofthe goods being released.

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 and the version of the API to be used. For example: application/vnd.hmrc.v0.1+json
Authorization required	An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

{
   "arrivals":[
      {
         "body":"<IE007>....</IE007>"
      }
   ]
}

<IE007>....</IE007>

Close section

Send an arrival notification

POST

Send a message to let the Office of 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 location header in the response will contain a URI and arrival ID for the arrival notification. This will allow you to retrieve the submission status and relating status messages. The submission status will be either “pending” or “success”. A “pending” status means the arrival notification has not got to the NCTS yet. A “success” status means the arrival notification is being processed by the NCTS.

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 and the version of the API to be used. For example: application/vnd.hmrc.v0.1+json
Authorization required	An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

Name	Description
Location required	The uri to retrieve the arrival notification, including arrival ID For example: /customs/transits/movements/arrivals/123456/messages/7898765

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 202 (Accepted)

<IE007>
</IE007>

Close section

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

Pull an arrival notification for an arrival ID

GET

Pull a specific arrival message which was sent to the Office of Destination within 21 days of the goods being released. Any arrival notifications that are more than 21 days old will be archived. Archived notifications will be return a “not found” 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

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.v0.1+json
Authorization required	An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

Name	Description
SubmissionStatus required	The status of the notification submission, either Pending or Success For example: Pending

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

{
  "arrival": {
    "body": "<IE007>....</IE007>"
    }
}

Close section

Send a message to confirm that the goods have been unloaded

POST

Send a message to the Office of Destination to let them know that the goods have been unloaded. This message is called an E_ULD_REM (IE044). You should use this message to let the Office of Destination know about any issues you found with the goods when they were unloaded. This couldinclude things like extra or missing boxes, or damaged or changed seals. You should notify them about any details that are different to what was recorded in the initial declaration.

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
Authorization required	An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

Name	Description
Location required	The uri to retrieve the arrival notification, including arrival ID For example: /customs/transits/movements/arrivals/123456/messages

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 202 (Accepted)

<IE044>...</IE044>

Close section

Resubmit an arrival notification

PUT

Resend an arrival notification to the Office of Destination if the first arrival notification was rejected. Arrival notifications will be rejected when the NCTS validation fails. This can happen for reasons, such as if:

• a guarantee against the Economic Operator Registration and Identification (EORI) number is not enough to cover the goods being transported
• the Movement Reference Number (MRN) has already been used on another arrival notification This message is called E_ARR_REJ (IE008).

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 and the version of the API to be used. For example: application/vnd.hmrc.v0.1+json
Authorization required	An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

Name	Description
Location required	The uri to retrieve the arrival notification, including arrival ID For example: /customs/transits/movements/arrivals/123456/message/123456

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 202 (Accepted)

<IE007>
</IE007>

Close section

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

Pull all messages relating to an arrival movement

GET

Pull all messages sent within 21 days of the goods being released relating to an arrival movement. You will only be able to retrieve these messages if you have the Economic Operator Registration and Identification (EORI) number associated with the arrival movement.

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
Authorization required	An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

{
   "messages":[
      {
         "date":"2020-12-31",
         "body":"<CC058A>....</CC058A>"
      },
      {
         "date":"2020-12-30",
         "body":"<CC058A>....</CC058A>"
      }
   ]
}

Close section

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

Pull a message relating to an arrival movement and message ID

GET

Pull all messages relating to a specific arrival movement and message ID. For example, this could include messages about route diversions or unloading permissions. Any messages more than 21 days old will be archived. Archived messages will be return a “not found” 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

Name	Description
Authorization required	An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

{
  date: "2020-12-30",
  body: "<CC058A>....</CC058A>"
}

Close section

/customs/transits/movements/departures

Pull all departure notifications

GET

Pull all departure messages sent to the Office of Departures within 21 days of the goods being released at their final destination.

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 and the version of the API to be used. For example: application/vnd.hmrc.v0.1+json
Authorization required	An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

{
   "departures":[
      {
        "date": "2021-01-15",
         "body":"<IE015>....</IE015>"
      },
      {
        "date": "2021-01-16",
         "body":"<IE015>....</IE015>"
      }
   ]
}

Close section

Send a departure notification

POST

Send a message to let the Office of Departure know that the goods are on route to their final destination. This message will be sent when the goods leave the Office of Departure. It is also called an E_DEC_DAT (IE015). The location header in the response will contain a URI and departure ID forthe departure notification. This will allow you to retrieve the submission status and relating status messages. The submission status will be either “pending” or “success”. A “pending” status means the departure notification has not got to the NCTS yet. A “success” status means the departure notification is being processed by the NCTS.

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 and the version of the API to be used. For example: application/vnd.hmrc.v0.1+json
Authorization required	An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

Name	Description
Location required	The uri to retrieve the departure notification, including departure ID For example: /customs/transits/movements/departures/123456

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 202 (Accepted)

<IE015>...</IE015>

Close section

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

Pull a departure notification for a departure ID

GET

Pull a specific departure message which was sent to the Office of Departure within21 days of the goods being released at their final destination. Any departure notifications that are more than 21 days old will be archived. Archived notifications will be return a “not found” 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

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: application/vnd.hmrc.v0.1+json
Authorization required	An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response headers

Name	Description
SubmissionStatus required	The status of the notification submission, either Pending or Success For example: Pending

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

<IE015></IE015>

{
  "date": "2021-01-15",
   "body":"<IE015>....</IE015>"
}

Close section

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

Pull all messages relating to a departure movement

GET

Pull all messages sent within 21 days of the goods being released relating to a departure movement. You will only be able to retrieve these messages if you have the Economic Operator Registration and Identification (EORI) number associated with the departure movement.

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
Authorization required	An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

{
   "messages":[
      {
         "date":"2020-12-31",
         "body":"<CC0XXA>....</CC0XXA>"
      },
      {
         "date":"2020-12-30",
         "body":"<CC0XXA>....</CC0XXA>"
      }
   ]
}

Close section

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

Pull a message relating to a departure movement and message ID

GET

Pull all messages relating to a specific departure movement and message ID. For example, this could include declaration rejected or Movement Reference Number (MRN) allocated messages. Any messages more than 21 days old will be archived. Archived messages will return a “not found” 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

Name	Description
Authorization required	An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Response

HTTP status: 200 (OK)

{
   "date":"2020-12-30",
   "body":"<CC0XXA>....</CC0XXA>"
}

Close section

Back to top

Get help with this page. Get help with this page.