This version is in beta - expect some breaking changes.
CTC Traders API
Available in Sandbox | Yes |
---|---|
Sandbox base URL | https://test-api.service.hmrc.gov.uk |
Available in Production | Yes |
Production base URL | https://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.
Endpoints
/customs/transits/movements/arrivals
/customs/transits/movements/arrivals/{arrivalId}
/customs/transits/movements/arrivals/{arrivalId}/messages
/customs/transits/movements/arrivals/{arrivalId}/messages/{messageId}
/customs/transits/movements/departures
/customs/transits/movements/departures/{departureId}
/customs/transits/movements/departures/{departureId}/messages
/customs/transits/movements/departures/{departureId}/messages/{messageId}