Skip to main content

CTC Traders API phase 5 service guide

CTC Traders API roadmap

CTC Traders API specification

NCTS Phase 5 Technical Interface Specification

Introduction

This guide explains how to use the Common Transit Convention (CTC) Traders API with your software.

The CTC Traders API allows traders to send and receive arrival and departure movements to and from the New Computerised Transit System (NCTS) for Great Britain and Northern Ireland.

Note: Current development focuses on small messages (0.5MB and below only). Development for messages larger than 0.5MB will begin at a later date.

Changelog

You can find the changelog in the ctc-traders-phase5-service-guide GitHub wiki.

Getting Started

These steps must be followed before you can use your software in the live environment and access our live API:

  1. Subscribe to the Developer Hub by registering for a developer account.
  2. Create an application by following the instructions on Using the Developer Hub.
  3. Subscribe to the CTC Traders API (V2.0 Beta) and to the Test User API using your test application.
  4. Read about the Government Gateway Authorisation. Before you can access the CTC Traders API, your software needs to authenticate using OAuth 2.0.
  5. Read guidance on the OAuth 2.0 standards required for all of HMRC’s APIs.
  6. Create test users before you can test your application.
  7. Download reference data to get Customs Offices List (COL) data to use for testing. Visit the EU’s reference data download page to download reference data.
  8. Test your application in the sandbox environment by following the steps in our Guide to Testing (currently unavailable).
  9. Complete the Application for Productions Checklist form (currently unavailable).
  10. Apply for production credentials through your developer account before you go live.
  11. Get your customers ready by asking them to apply for an EORI number and a Government Gateway account.

Get your customers ready

Your customers need to sign up to the CTC Traders API and provide you with the following details:

  • GB Economic Operators Registration and Identification (EORI) number
  • VAT details (optional)
  • Standard Industrial Classification (SIC) code
  • company or organisation details:
    • unique tax reference (UTR) number
    • registered company name (this must be an exact match)
    • registered company address
    • date of company establishment

They will also need to provide:

  • email address
  • contact details

Process flows

Process flows are available in the NCTS Phase 5 Technical Interface Specification.

NCTS Message Details

XSD - XML Schema Definition

The API uses XSD templates to validate all the Information Exchange (IE) messages that come into the system.

If there are any problems, the IE message will be rejected with a 400 BadRequest status which will contain an explanation of the problem.

The XML schemas are available for download here.

Information Exchange messages

These are standard messages sent to and received from NCTS. For details, see the NCTS Phase 5 Technical Interface Specification.

API features

Rate limits

Our API Platform’s standard rate limit is 3 requests per second. If you need a higher rate limit, you must give us more information about data and limit forecasts when filling in the Application for Production Credentials checklist form (currently unavailable).

Get Support

Before you get in touch, find out if there are any planned API downtime or technical issues by checking:

If you have specific questions about the CTC Traders API, get in touch with our Software Developer Support Team.

You’ll get an initial response in 2 working days.

Email us your questions to SDSTeam@hmrc.gov.uk. We might ask for more detailed information when we respond.

Useful Links