This version is in beta - expect some breaking changes.

CTC Traders 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 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 are releasing Phase 5 functionality incrementally starting with the IE015C Departure Declaration endpoint to create a new departure movement.

  • Read our Roadmap for important dates and service updates

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.

Percent-encoding of parameters in request URLs

When writing code to use date filters in request URLs, you must always use percent-encoding. This is because some common characters used in dates and timestamps are not allowed to be used in URLs.

If you do not use percent-encoding you will get a 400 Bad Request as a default response.

For example:

  • the timestamp 2021-06-21T09:00+00:00 should be encoded as 2021-06-21T09%3A00%2B00%3A00

When formatting query parameters into the request URL for date and time filtering functionality, you must only use the date and time format as specified in Developer Hub. You’ll then be using the common ISO 8601 standard 2021-06-21T09:00+00:00 that is compatible with our CTC Traders API.

Here are more examples in different programming languages:

Java

java.net.URLEncoder.encode("2021-04-30T16:08:31+00:00");

Python:

from urllib.parse import quote

quote('2021-04-30T16:08:31+00:00')

C#:

Uri.EscapeDataString("2021-04-30T16:08:31+00:00");

When sending requests to HMRC APIs you must always use percent-encoding within the URL to avoid getting any 400 Bad Requests.

You should also note:

  • some common data types described in the Reference Guide on Developer Hub contain characters that are not valid for use in URLs
  • some software libraries do the percent-encoding for you automatically when you develop software using their facilities. Your web framework might also do this automatically for you

Find out more

There are many frameworks and libraries that can handle percent-encoding for you. For background information about percent-encoding, we recommend you read (all links open in a new window):

Errors

Here is the list of 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

413 Request Entity Too Large: If the client request body is too large for the given endpoint

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

413 Request Entity Too Large: If the client request body is too large for the given endpoint

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.

Skip to main content

Endpoints

/customs/transits/movements/departures

Send a Declaration Data message
POST

Send a Declaration Data message, to let the office at destination know that the goods are on their way. This notification will be sent when the goods leave the Office of Departure. It is also called an E_DEC_DAT (IE015).

The response will contain a URI and departure ID for the Declaration Data. This will allow you to retrieve messages related to the movement.

If the user is not enrolled for an EORI number, they will receive an HTTP Forbidden 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

Request headers Table
Name Description
Content-Type
required

Specifies the format of the request body, which must be XML.

For example: application/xml
Accept
required

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

For example: application/vnd.hmrc.2.0+json
Authorization
required
An OAuth 2.0 Bearer Token with the common-transit-convention-traders scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 202 (Accepted)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/departures/abc123efg"
    }
  },
  "departureId": "abc123efg",
  "messageType": "IE015",
  "body": "<CC015C>...</CC015C>"
}

Error scenarios

Error scenarios table
Scenario HTTP status Code

The request body is too large

413 (Payload Too Large)

REQUEST_ENTITY_TOO_LARGE

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section

Skip to main content