Common Transit Convention Traders API end-to-end service guide
This guide explains how to use the new Common Transit Convention (CTC) Traders API with your software. The API will allow your software to send and receive movement notifications and status messages to and from the New Computerised Transit System (NCTS).
Our CTC Traders API is now live in production for Great Britain movements and Northern Ireland.
Read our Roadmap to find out what we have planned.
The Common Transit Convention allows traders to move goods across CTC member states without paying import duties at every border they cross.
Under the agreement, CTC member countries only need to pay duties in the country of destination.
All goods will be subject to duties and other charges when they enter the EU, or enter the UK from the EU.
The CTC Traders API allows traders to send and receive arrival and departure notifications for Great Britain and Northern Ireland movements.
Replacing the NCTS XML API
Volumes of Common Transit movements are expected to increase significantly now that the UK is no longer part of the European Union. The current NCTS XML API channel needs to change to cope with this forecasted increase.
In order to make sure we provide a reliable and fast service we have introduced the CTC Traders API to replace the current NCTS XML API.
If you have never used the NCTS XML API channel, you’ll only need to refer to the new CTC Traders API descriptions.
Comparison between the existing and the new API
The table shows how the new API uses different coding, compared to the existing NCTS XML API.
|Activity||NCTS XML API||CTC Traders API|
|Submit Arrival Notification (IE007)||SOAP authorisation (includes username and password in clear text)||Government Gateway authorisation (OAuth 2.0 token)|
|Create action||SOAP wrapper, with embedded instruction||RESTful interface, action inferred from the URL|
|POST API Payload||SOAP with EDIFACT body||Information Exchange message (IE) XML|
|GET API Payload||SOAP with EDIFACT body||JSON and IE XML|
The diagrams show the difference between the current EDIFACT and new XML payloads for GET and POST messages.
The current POST message payload consists of 4 layers:
- Outer layer: HTTPS
- Inside that: XML SOAP transport layer which includes
- WSSE authentication, consisting of a clear text username and password
- a command (eg getDocument)
- Within that: the EDIFACT ‘wrapper’
- At the centre: the true payload payload which is an XML list
The new POST payload message consists of 2 layers:
- Outer layer: RESTful standards HTTPS and OAuth 2.0 token authentication
- At the centre: the true payload which is an XML message eg IE007
The current GET message payload consists of 4 layers:
- Outer layer: HTTPS
- WIthin that: XML SOAP transport layer, which includes
- WSSE authentication, consisting of clear text username and password
- a command, eg getDocument
- Within that: the EDIFACT ‘wrapper’
- At the centre: the true payload - the GET message
The new GET payload consists of 3 layers:
- Outermost layer: RESTful standards HTTPS and OAuth 2.0 token authentication
- Middle layer: a JSON list
- At the centre: the true payload which is the XML
Advantages of the new CTC Traders API
- Our systems will be ready for the expected increase in CTC movements
- They will greatly improve security
- Testing and maintenance of the platform will be more efficient
What you’ll need to do
Read the documentation
Testing your software
You can now test movements to or from both Great Britain and Northern Ireland using the Trader Test service.
We have published a Guide to Testing. This will signpost you to all the information you need and what to do.
This will include:
- all the information you need to get set up for testing
- a link to the CTC Traders API Test Pack which includes scenarios and test data for both Great Britain and Northern Ireland
- step by step guidance for how to test
Trader Test will automatically simulate and give you responses just like in a real life scenario. You can also request NCTS support staff to generate the manual responses as if Border Force staff are processing your goods.
Validate your XML
Use our XSD files to validate your XML
Find out which functionality we’ve released
Check the roadmap to see what you can test now and what’s coming soon.
See the list of in-scope messages
Check which IE messages are applicable to the CTC Traders API.
Read about the current NCTS API channel specifications
The specifications for the current NCTS describe the business rules and logic for building software to connect with NCTS. These rules are applicable to both the current and the new APIs.
Visit the New Computerised Transit System: technical specifications to read about the NCTS system that’s currently in operation.
Note, this is the specification document for the outgoing NCTS XML API channel, so there will be discrepancies. For example, the CTC Traders API will not use an EDIFACT wrapper or SOAP.
Learn how to apply OAuth 2.0
Read guidance on the OAuth 2.0 standards required for HMRC APIs.
Use the Developer Hub tutorials
If you’re new to HMRC APIs, use the Developer Hub tutorials to find out what you need to know about working with us.
We have support in place to help you with any questions or problems you might have with the CTC Traders API. Find out to get help.
Check service availability
Before you get in touch, check out whether API downtime or technical issues are the problem. Check the HMRC API platform availability.
The steps you need to take before you can use your software in the live environment:
- Register and subscribe to the Developer Hub Register for a developer account and subscribe to both the CTC Traders API and Create Test User API.
- Understand Government Gateway authorisation In order to use the CTC Traders API your software needs to interact using OAuth 2.0.
- Create test user To start testing your software, you need to generate test users.
- Download reference data To get Customs Offices List (COL) data to use for testing, visit the EU’s reference data download page.
- Apply to go live You need to apply for production credentials through your developer account.
- Get your customers ready For example, ask them to apply for an EORI number and a Government Gateway account.
Data cap and using filters
When you submit a request to 'GET all movements’ against a single EORI enrolment, we’ll limit the number of movements you get back to 5,000 movements.
You can use filters when you ‘GET all movements’ so that you only get the movements that have been updated since a specified date and time. This affects the ‘GET all movements arrivals’ and ‘GET all movement departure’ endpoints.
If you do not use filters:
- you’ll only get up to the most recently updated 5,000 movements, within the last 28 days
- you will not get any additional movements above this cap, within the last 28 days
In order to manage the limit you need to regularly poll using a filter date and time of the last poll. This will ensure your list of movements requested is less than 5,000.
You must also note:
- the amount of responses that we send back to you will be capped at 5,000 for one single Economic Operator Registration and Identification (EORI) enrolment
- the EORI enrolment for your application might not be the same as the trader’s EORI associated with a movement
- the cap is not related to the movement EORI in the XML messages
- if your movements are split over multiple EORI enrolments then each enrolment will have a separate 5,000 cap
- if you have over 5,000 active movements, the JSON payload will tell you this cap has happened and how many movements have not been sent to you. For example, the JSON message will state that 5,000 movements of a total of 6,433
- only the most recent 5,000 data movements in last 28 days will be returned. This is because we only store message data from the last 28 days.
Push pull notifications
Our automated service can send you notification updates about new messages from NCTS. This functionality will send you a notification each time there is a new message for you to read.
This will mean your:
- software will not have to poll for updated information
- requests are unlikely to be rate limited because they’ll not be as frequent
- network usage will also go down because you’ll not need to poll
You should also note:
- smaller messages of less than 100KB will be sent to you directly by our system in the payload of the push notification
- messages greater than or equal to 100KB will not include the XML in the push notification
- the push notification will have a field called messageURI which will contain the relative path to the full XML message
- for messages larger than 100KB you must use the URI to download the XML message from the CTC Traders API
For more information on how to configure and test this functionality read our Guide to Testing.
Review the message flow diagrams to see the correct message sequences:
- End-to-end happy path diagram - the end-to-end process of transporting goods using the CTC Traders API
- Sending an Arrival Notification diagram - for sending an Arrival Notification to NCTS using the CTC Traders API
Version 0.11 16 July 2021 - Added Push Pull Notifications Service info
Version 0.10 22 June 2021 - Added cap and filter information
Version 0.9: 15 June 2021 - v2 updated to include 917 XSD file info and XML Negative Acknowledgement (IE917) and rephrased descriptions. Also added link to 917 XSD and added the XSD to the zip file of all XSDs. v1 originally published version
Version 0.8: 28 May 2021 - Added updated information about Northern Ireland functionality now live in production environment.
Version 0.7: 18 May 2021 - Minor content update.
Version 0.6: 22 April 2021 - Added updated information about new CTC Trader Test Pack, testing can now be done for NI plus NI live functionality planned for late May 2021.
Version 0.5: 13th April 2021 - Added revised bullet point information about CTC Traders API go live plus NI functionality planned to go live around April 2021.
Version 0.4: 10 February 2021 - Added release date for the GB version of the API.
Version 0.3 11 September 2020 - Added more XSD files and added to list of supported IE messages.
Version 0.2: 6 August 2020 - Added further detail in reference to the XSD files.
Version 0.1: 15 July 2020 - First release.