This version is in beta - expect some breaking changes.

CTC Traders Test Support API

Dates and amounts
Date Amount
Version and status
Available in Sandbox Yes
Sandbox base URL https://test-api.service.hmrc.gov.uk
Available in Production No

Overview

Use the CTC Traders Test Support API to inject departure and arrival movement notifications as if they have come from a customs office of departure or destination through the New Computerised Transit System (NCTS).

You should read:

  • Roadmap to review our progress and to learn about what you can test
  • Tutorials to learn how to develop your own client applications, including example clients, for this API

Changelog

You can find the changelog in the common-transit-convention-traders-test-support GitHub wiki.

How to get set up for testing

Follow these steps:

  1. Register for a developer account.

  2. Create an application.

  3. Subscribe to any API you might be working on. We suggest the Create Test User API, the CTC Traders API and this API.

  4. Create a Client ID and Client Secret.

  5. Use the Create Test User API to get a user ID, password, EORI enrolment and other test details.

How to use this API

This API is not connected to the NCTS core, so you can use it for any test scenario you choose.

It’s up to you to trigger the response messages in the order you require. Valid response message types are listed below.

Follow these steps:

  1. Use the CTC Traders API to send messages from a trader to the NCTS.

  2. Use this API to inject a response. See the table below for a list of supported messages that you can inject.

  3. Use the CTC Traders API to retrieve a list of your messages for this movement. This will include both your trader and your injected NCTS messages.

Messages you can inject now

Title Description Instruction
Inject an amendment acceptance message (IE004) Inject an amendment acceptance message from the office of departure (IE004) Specify "IE004" for the messageType field
Inject an invalidation decision message (IE009) Inject an invalidation decision message to be sent to the holder of the transit procedure (IE009) Specify "IE009" for the messageType field
Inject declaration received message (IE928) Inject a positive acknowledgement of a departure declaration message (IE015) Specify "IE928" for the messageType field
Inject a goods release notification (IE025) Inject a message from the office at destination that the trader can release the goods Specify "IE025" for the messageTypefield
Inject an MRN allocated message (IE028) Inject a message from the office at departure allocating a Movement Reference Number (MRN) Specify "IE028" for the messageType field
Inject a goods released for transit message (IE029) Inject a message from the office at departure to say the goods are released for transit Specify "IE029" for the messageType field
Inject a control decision notification (IE060) Inject a message from the office at departure to tell the trader they wish to carry out a control of the goods Specify "IE060" for the messageTypefield
Inject an unloading permission (IE043) Inject an unloading permission message to inform the trader that they are authorised to unload the goods at the authorised place Specify "IE043" for the messageTypefield
Inject a rejection from office of departure (IE056) Inject a rejection from office of departure message to inform the trader that the office of departure has rejected the message Specify "IE056" for the messageTypefield
Inject a rejection from office of destination (IE057) Inject a rejection from office of destination message to inform the trader that the office of destination has rejected the message Specify "IE057" for the messageTypefield
Inject a request on non-arrived movement (IE140) Inject a non-arrived movement message to the trader indicating that there is insufficient information to discharge the transit Specify "IE140" for the messageTypefield
Inject a request on recovery notification (IE035) Inject a recovery notification from office of departure to inform the trader about recovery Specify "IE035" for the messageTypefield
Inject a no release for transit message (IE051) IInject a message from the office at departure that the movement cannot be released for transit Specify "IE051" for the messageTypefield
Inject a guarantee not valid message (IE055) Inject a message from the office of departure to the trader at departure that their guarantee is not valid Specify "IE055" for the messageTypefield
Inject a Write-Off notification message (IE045) Inject a message from the office at departure that the transit movement has been discharged Specify "IE045" for the messageTypefield
Inject a Discrepancies message (IE019) Inject a message from the office at departure that the transit movement has major discrepancies Specify "IE019" for the messageTypefield
Inject a Forwarded Incident Notification To ED message (IE182) Inject a message from the office at departure that the transit movement require investigation by a custom officer Specify "IE182" for the messageTypefield

Reference materials

Our XSD files

You can check your XML files against our XSD files.

NCTS Phase 5 Technical Interface Specification

The specification provides a list of messages, message details, and process flow diagrams.

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 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 JSON message.
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.

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

Skip to main content

Endpoints

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

Inject a fake NCTS Phase 5 arrival message
POST

Inject a message type into the test NCTS database for a given 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-test-support scope.

Path parameters

Path parameters table
Name Description
arrivalId
string
required

The ID specifying the arrival.

For example: abcdef1234567890

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format, which must be JSON, and the version of the API to be used.

For NCTS phase 5 and version 2.0 of this API, use the example value.

For example: application/vnd.hmrc.2.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-traders-test-support scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

{
     "message": {
         "messageType": "IEXXX"
     }
 }

Responses

HTTP status 201 (Created)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/arrivals/1234567890abcdef/messages/1234567890abcdef"
    },
    "arrival": {
      "href": "/customs/transits/movements/arrivals/1234567890abcdef"
    }
  },
  "arrivalId": "1234567890abcdef",
  "messageId": "1234567890abcdef",
  "messageType": "IEXXX",
  "body": "<CCXXX>...</CCXXX>"
}


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

Inject a fake NCTS Phase 5 departure message
POST

Inject a message type into the test NCTS database for a given 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-test-support scope.

Path parameters

Path parameters table
Name Description
departureId
string
required

The ID specifying the departure.

For example: abcdef1234567890

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format, which must be JSON, and the version of the API to be used.

For NCTS phase 5 and version 2.0 of this API, use the example value.

For example: application/vnd.hmrc.2.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-traders-test-support scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

{
     "message": {
         "messageType": "IEXXX"
     }
 }

Responses

HTTP status 201 (Created)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/departures/1234567890abcdef/messages/1234567890abcdef"
    },
    "departure": {
      "href": "/customs/transits/movements/departures/1234567890abcdef"
    }
  },
  "departureId": "1234567890abcdef",
  "messageId": "1234567890abcdef",
  "messageType": "IEXXX",
  "body": "<CCXXX>...</CCXXX>"
}


Close Section

Skip to main content