Skip to main content
GOV.UK
Menu
HMRC Developer Hub
  • Documentation
  • Applications
  • Support
  • Service availability

GOV.UK uses cookies to make the site simpler. Find out more about cookies

  1. Home
  2. API Documentation
  3. Common Transit Convention Traders Test Support API v1.0 (Beta)
  • Register
  • Sign in
  • Overview
  • Versioning
  • Errors
  • Endpoints
 

This version is in beta - expect some breaking changes.

CTC Traders Test Support API

Available in SandboxYes
Sandbox base URLhttps://test-api.service.hmrc.gov.uk
Available in ProductionNo

Overview

This API allows testers to inject departure and arrival movement notifications as if they have come from the office of departure or the office of destination by the New Computerised Transit System (NCTS).

To review our progress and to see what you can test, take a look at our Roadmap.

For more information about how to develop your own client applications, including example clients for this API, see Tutorials.



How to get set up for testing

Follow these steps to get set up for testing.

  1. Register for a developer account.

  2. Create an application.

  3. Subscribe to any API you might be working on. We suggest Create Test User API along with Common Transit Convention Traders API and Common Transit Convention Traders Test Support API (which is on this page).

  4. Create a Client ID and Client Secret.

  5. Use the Create Test User API to get a user ID, password, EORI enrolment and other test details.



How to use the CTC Trader Test Support API

You can use this API for any test scenario you choose. It is not connected to the NCTS core. It’s up to you to trigger the response messages in the order you require. Valid response message types are listed below.

  1. Send messages from a trader to NCTS using the CTC Traders API. This could be IE014, IE015, IE007 or IE044. See message we support for more details.

  2. Inject a response using the Common Transit Traders Test Support API. See below.

  3. GET a list of your messages for this movement from the CTC Traders API. This will include both your trader and your injected NCTS messages.



Messages you can inject now

Inject an Arrival Notification rejection message (IE008) Inject a message from the office of destination rejecting the traders Arrival Notification (IE007) Specify "IE008" for the messageType field
Inject an unloading permission message (IE043) Inject an unloading permission message to the trader at destination Specify "IE043" for the messageType field
Inject a write-off notification (IE045) Inject a message from the office at departure that the transit movement has been discharged Specify "IE045" for the messageType field
Inject an unloading remarks rejection message (IE058) Inject a message from the office at destination that there are errors in the trader's unloading remarks message (IE044) Specify "IE058" for the messageType field
Inject declaration received message (IE928) (IE028) Inject a positive acknowledgement of a departure declaration message (IE015) Specify "IE928" for the messageType field
Inject an MRN allocated message (IE028) Inject a message from the office at departure allocating a Movement Reference Number (MRN) Specify "IE028" for the messageType field
Inject a goods released for transit message (IE029) Inject a message from the office at departure to say the goods are released for transit Specify "IE029" for the messageType field
Inject a declaration rejection message (IE016) Inject a message from the office at departure rejecting a declaration data message (IE015) Specify "IE016" for the messageType field
Inject a no release for transit message (IE051) Inject a message from the office at departure that the movement cannot be released for transit Specify "IE051" for the messageTypefield
Inject a guarantee not valid message (IE055) Inject a message from the office of departure to the trader at departure that their guarantee is not valid Specify "IE055" for the messageTypefield
Inject a control decision notification (IE060) Inject a message from the office at departure to tell the trader they wish to carry out a control of the goods Specify "IE060" for the messageTypefield
Inject a good release notification (IE025) Inject a message from the office at destination that the trader can release the goods Specify "IE025" for the messageTypefield



Reference materials

CURL commands

Use these CURL commands to simulate your application’s actions and messages, plus the actions and messages that would come back from NCTS.

See IE015 CURL command

curl --location --request POST 'https://test-api.service.hmrc.gov.uk/customs/transits/movements/departures' \
--header 'Authorization: Bearer <Enter your Bearer Token>' \
--header 'Content-Type: application/xml' \
--data-raw \
"
<CC015B>
    <SynIdeMES1>UNOC</SynIdeMES1>
    <SynVerNumMES2>3</SynVerNumMES2>
    <MesRecMES6>NCTS</MesRecMES6>
    <DatOfPreMES9>20201117</DatOfPreMES9>
    <TimOfPreMES10>0935</TimOfPreMES10>
    <IntConRefMES11>25973103497074</IntConRefMES11>
    <AppRefMES14>NCTS</AppRefMES14>
    <MesIdeMES19>1</MesIdeMES19>
    <MesTypMES20>GB015B</MesTypMES20>
    <HEAHEA>
        <RefNumHEA4>TRATESTDEC112011170935</RefNumHEA4>
        <TypOfDecHEA24>T1</TypOfDecHEA24>
        <CouOfDesCodHEA30>IT</CouOfDesCodHEA30>
        <AutLocOfGooCodHEA41>954131533-GB60DEP</AutLocOfGooCodHEA41>
        <CouOfDisCodHEA55>GB</CouOfDisCodHEA55>
        <TraModAtBorHEA76>3</TraModAtBorHEA76>
        <IdeOfMeaOfTraCroHEA85>NC15 REG</IdeOfMeaOfTraCroHEA85>
        <NatOfMeaOfTraCroHEA87>GB</NatOfMeaOfTraCroHEA87>
        <ConIndHEA96>0</ConIndHEA96>
        <NCTSAccDocHEA601LNG>EN</NCTSAccDocHEA601LNG>
        <TotNumOfIteHEA305>1</TotNumOfIteHEA305>
        <TotNumOfPacHEA306>10</TotNumOfPacHEA306>
        <TotGroMasHEA307>1000</TotGroMasHEA307>
        <DecDatHEA383>20201117</DecDatHEA383>
        <DecPlaHEA394>Dover</DecPlaHEA394>
        <SpeCirIndHEA1>C</SpeCirIndHEA1>
        <ComRefNumHEA>HQDOV018</ComRefNumHEA>
        <SecHEA358>1</SecHEA358>
        <CodPlUnHEA357>MONOPOLI001</CodPlUnHEA357>
    </HEAHEA>
    <TRAPRIPC1>
        <NamPC17>NCTS UK TEST LAB HMCE</NamPC17>
        <StrAndNumPC122>11TH FLOOR, ALEX HOUSE, VICTORIA AV</StrAndNumPC122>
        <PosCodPC123>SS99 1AA</PosCodPC123>
        <CitPC124>SOUTHEND-ON-SEA, ESSEX</CitPC124>
        <CouPC125>GB</CouPC125>
        <TINPC159>GB954131533000</TINPC159>
    </TRAPRIPC1>
    <TRACONCO1>
        <NamCO17>NCTS UK TEST LAB HMCE</NamCO17>
        <StrAndNumCO122>11TH FLOOR, ALEX HOUSE, VICTORIA AV</StrAndNumCO122>
        <PosCodCO123>SS99 1AA</PosCodCO123>
        <CitCO124>SOUTHEND-ON-SEA, ESSEX</CitCO124>
        <CouCO125>GB</CouCO125>
        <TINCO159>GB954131533000</TINCO159>
    </TRACONCO1>
    <TRACONCE1>
        <NamCE17>NCTS UK TEST LAB HMCE</NamCE17>
        <StrAndNumCE122>ITALIAN OFFICE</StrAndNumCE122>
        <PosCodCE123>IT99 1IT</PosCodCE123>
        <CitCE124>MILAN</CitCE124>
        <CouCE125>IT</CouCE125>
        <TINCE159>IT11ITALIANC11</TINCE159>
    </TRACONCE1>
    <CUSOFFDEPEPT>
        <RefNumEPT1>GB000060</RefNumEPT1>
    </CUSOFFDEPEPT>
    <CUSOFFTRARNS>
        <RefNumRNS1>FR001260</RefNumRNS1>
        <ArrTimTRACUS085>202011190935</ArrTimTRACUS085>
    </CUSOFFTRARNS>
    <CUSOFFDESEST>
        <RefNumEST1>IT018105</RefNumEST1>
    </CUSOFFDESEST>
    <CONRESERS>
        <ConResCodERS16>A3</ConResCodERS16>
        <DatLimERS69>20201125</DatLimERS69>
    </CONRESERS>
    <SEAINFSLI>
        <SeaNumSLI2>1</SeaNumSLI2>
        <SEAIDSID>
            <SeaIdeSID1>NCTS001</SeaIdeSID1>
        </SEAIDSID>
    </SEAINFSLI>
    <GUAGUA>
        <GuaTypGUA1>1</GuaTypGUA1>
        <GUAREFREF>
            <GuaRefNumGRNREF1>09GB00000100000M0</GuaRefNumGRNREF1>
            <AccCodREF6>AC01</AccCodREF6>
        </GUAREFREF>
    </GUAGUA>
    <GOOITEGDS>
        <IteNumGDS7>1</IteNumGDS7>
        <GooDesGDS23>Daffodils</GooDesGDS23>
        <GooDesGDS23LNG>EN</GooDesGDS23LNG>
        <GroMasGDS46>1000</GroMasGDS46>
        <NetMasGDS48>950</NetMasGDS48>
        <PACGS2>
            <MarNumOfPacGS21>AB234</MarNumOfPacGS21>
            <KinOfPacGS23>BX</KinOfPacGS23>
            <NumOfPacGS24>10</NumOfPacGS24>
        </PACGS2>
        <TRACORSECGOO021>
            <TINTRACORSECGOO028>GB954131533000</TINTRACORSECGOO028>
        </TRACORSECGOO021>
        <TRACONSECGOO013>
            <TINTRACONSECGOO020>IT17THEBOSS42</TINTRACONSECGOO020>
        </TRACONSECGOO013>
    </GOOITEGDS>
    <ITI>
        <CouOfRouCodITI1>GB</CouOfRouCodITI1>
    </ITI>
    <CARTRA100>
        <TINCARTRA254>GB954131533000</TINCARTRA254>
    </CARTRA100>
</CC015B>
"

See IE016 CURL command

curl --location --request POST 'https://test-api.service.hmrc.gov.uk/test/customs/transits/movements/departures/{deptId}/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Enter your Bearer Token>' \
--data-binary @- << EOF
{
    "message": {
        "messageType": "IE016"
    }
}
EOF

See Get Dept Id CURL command

curl --location --request GET 'https://test-api.service.hmrc.gov.uk/customs/transits/movements/departures/{deptId}' \
--header 'Accept: application/vnd.hmrc.1.0+json' \
--header 'Authorization: Bearer <Enter your Bearer Token>'

Our Postman test scripts

These were created by us in November 2020. These will not be monitored or updated.

Our XSD files

You can check your XML files against our XSD files.

Download the mapping document

This has plain English header descriptions, XML and EDIFACT code.

Trader Test Pack for GB

This contains test scenarios that you can use.

NCTS API channel specifications

See a list of messages, message content and sequence diagrams.

Note, this is NOT the specifications document for the new CTC Traders API. For example, the CTC Traders API will not use an EDIFACT wrapper or SOAP. A new version will be issued early in 2021.

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: If JSON 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

501 Not Implemented: If user attempts to POST a message and the message type isn't currently supported

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

/test/customs/transits/movements/arrivals/{arrivalId}/messages
Inject a fake NCTS Arrival Message
POST

Inject a message type into the test NCTS database for a given Arrival Movement.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the common-transit-convention-traders-test-support scope.

Path parameters

Path parameters table
Name Description
arrivalId
string
required

The ID specifying the Arrival

For example: 1

Request headers

Request headers Table
Name Description
Content-Type
required

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


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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Request

{
     "message": {
         "messageType": "IEXXX"
     }
 }

Response

HTTP status: 201 (Created)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/arrivals/1/messages/2"
    },
    "arrival": {
      "href": "/customs/transits/movements/arrivals/1"
    }
  },
  "arrivalId": "1",
  "messageId": "2",
  "messageType": "IEXXX",
  "body": "<CCXXX>...</CCXXX>"
}
Close section
/test/customs/transits/movements/departures/{departureId}/messages
Inject a fake NCTS Departure Message
POST

Inject a message type into the test NCTS database for a given Movement Departure.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the common-transit-convention-traders-test-support scope.

Path parameters

Path parameters table
Name Description
departureId
string
required

The ID specifying the Departure

For example: 1

Request headers

Request headers Table
Name Description
Content-Type
required

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


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

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention for other request headers which will become mandatory.

Request

{
     "message": {
         "messageType": "IEXXX"
     }
 }

Response

HTTP status: 201 (Created)

{
  "_links": {
    "self": {
      "href": "/customs/transits/movements/departures/1/messages/2"
    },
    "departure": {
      "href": "/customs/transits/movements/departures/1"
    }
  },
  "departureId": "1",
  "messageId": "2",
  "messageType": "IEXXX",
  "body": "<CCXXX>...</CCXXX>"
}
Close section
Skip to main content
Is this page not working properly? Is this page not working properly?
  • Cookies
  • Privacy policy
  • Terms and conditions
  • Help using GOV.UK
  • Accessibility statement

Open Government Licence

All content is available under the Open Government Licence v3.0, except where otherwise stated

© Crown Copyright