This version is in beta - expect some breaking changes.

CTC Traders Test Support API API

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 came from the Office of Departure and Office of Destination via the New Computerised Transit System (NCTS).

We will continue to add endpoints as we finish developing them. To review our progress and to see what you can test, take at look at our Roadmap.

Further details of the User Application 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: 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.

Endpoints

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

Inject a fake NCTS Arrival Message

POST

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

Path parameters

Path parameters table
Name	Description
arrivalId string required	The ID specifying the Arrival For example: `1`

Request headers

Request headers Table
Name	Description
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 for other request headers which will become mandatory.

Request

{
     "message": {
         "messageType": "IE008"
     }
 }

Response

HTTP status: 201 (Created)

Close section

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

Inject a fake NCTS Departure Message