Table of contents

Common Transit Convention Traders API end-to-end service guide


This guide explains how you can use our 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).

In 2021, UK traders will need to move from using the NCTS XML API to the new CTC Traders API.

Come back for regular updates

We are updating this guide as we add more functionality to our API, new technical specifications and other items we hope you find useful.

Overview

Right now, goods that can move freely within the UK can move across the EU freely too. This will change after the end of the transition period on 31 December 2020. Then, those goods will be subject to duties and other charges when they enter the EU, or enter the UK from the EU.

From 2021, if UK traders want to defer paying these duties and other charges, they can move the goods under the Common Transit Convention. This will allow traders to move goods across a number of countries, without having to pay import duties every time they cross a border. They will only have to complete the paperwork and pay any duties they owe, once they reach their destination country.

The API will allow traders to send and receive arrival and departure notifications to customs and border offices.

Why we are creating a new CTC Traders API

Common Transit will be a key procedure for moving goods between the United Kingdom and Europe. This will mean that declaration volumes will increase significantly. In order to make sure we provide a reliable and fast service we are introducing the new CTC Traders API to replace the current NCTS XML API.

Changes that come with the new CTC Traders API

The table below gives you a brief outline of 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 (include username and password in clear text) Government Gateway authorisation (OAuth2 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

Improvements with the CTC Traders API:

  • being ready for the expected increase in CTC movements
  • greatly improving security
  • making it easier to test and maintain

How we can help you with these changes

CTC Traders API specifications

Review our CTC Traders API specifications, endpoints and error messages.

CTC Trader Test Support API specifications

Check our CTC Traders Test Support API specifications endpoints.

XSD files

Look at our XSD files so you can validate your XML. We are working on an XML field mapping guide and we will share that with you as soon as we can.

Our roadmap

See our roadmap to see what you can test now.

See the messages we support

See the IE messages our API supports to get a clear understanding of your tasks with the CTC Traders API.

Check NCTS API channel specifications

Visit NCTS Phase 4 Technical Interface Specifications (TIS) to see a list of messages, message content and sequence diagrams.

Note, this is NOT the specifications document for the new CTC Traders API. So, there will be discrepancies. For example, the CTC Traders API will not use an EDIFACT wrapper or SOAP.

O-Auth2

Understand authorisation using guidance from the Developer Hub.

Developer Hub tutorials

Take advantage of Developer Hub tutorials to find out what you need to know about working with us.

Find support

We have support in place to help you with any questions or problems you might have to do with the CTC Traders API. See how we can support you.

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.

End-to-end process

This section shows you how the API fits into various end-to-end user journeys. It aims to help you understand how your software needs to interact with HMRC systems after the changes.

The path to going live with our API

Here are steps you need to take before you can use your software in the live environment:

  1. Register and subscribe to the Developer Hub
    Register for a developer account and subscribe to the services your need to use.
  2. Understand Government Gateway authorisation
    In order to use the CTC Traders API your software needs to interact with Government Gateway by using OAuth2.
  3. Create test user
    To start testing your software, you need to generate test users.
  4. Download reference data
    To get Customs Offices List (COL) data to use for testing, visit the EU’s reference data download page.
  5. Apply to go live
    You need to apply for production credentials through your developer account.
  6. Get your customers ready For example, ask them to apply for an EORI number and a Government Gateway account.

When these changes are happening

We will release the new CTC Traders API into the NCTS production environment in Spring 2021.

What’s happening for Northern Ireland transit

From 1 January 2021, the submission channel for Northern Ireland departure and arrival notification messages will initially be by email only. This is a temporary solution while we continue to work on getting the new API to also serve Northern Ireland.

Journey diagrams

Below are two diagrams that give you an overview of the new processes involving the CTC Traders API:

CTC Traders API specifications
Create Test User API

Changelog

Version 0.3

11 September 2020

What changed:

  • Added more XSD files, link to our roadmap, supported IE messages and a link to our Test API specifications page.

Version 0.2

6 August 2020

What changed:

  • Added detail in reference to the XSD files and a proviso to the NCTS channel specifications (TIS) document

Version 0.1

15 July 2020

  • 1st release.