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

This API allows testers to inject departure and arrival movement notifications as if they have come from the office of departure or the office of destination by the New Computerised Transit System (NCTS).

To review our progress and to see what you can test, take a look at our Roadmap.

For more information about how to develop your own client applications, including example clients for this API, see Tutorials.



How to get set up for testing

Follow these steps to get set up for testing.

  1. Register for a developer account.

  2. Create an application.

  3. Subscribe to any API you might be working on. We suggest Create Test User API along with Common Transit Convention Traders API and Common Transit Convention Traders Test Support API (which is on this page).

  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 the CTC Trader Test Support API

You can use this API for any test scenario you choose. It is not connected to the NCTS core. It’s up to you to trigger the response messages in the order you require. Valid response message types are listed below.

  1. Send messages from a trader to NCTS using the CTC Traders API.

  2. Inject a response using the Test Support API. See the following table for a list of supported messages you can inject.

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



Messages you can inject now

Inject declaration received message (IE928) (IE028) Inject a positive acknowledgement of a departure declaration message (IE015) Specify "IE928" for the messageType field
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



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

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: If JSON 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

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

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

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

Inject a fake NCTS 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: 1

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/1/messages/2"
    },
    "departure": {
      "href": "/customs/transits/movements/departures/1"
    }
  },
  "departureId": "1",
  "messageId": "2",
  "messageType": "IEXXX",
  "body": "<CCXXX>...</CCXXX>"
}


Close Section

Skip to main content