GOV.UK
This version is in beta - expect some breaking changes.
CTC Traders Test Support API
| Available in Sandbox | Yes |
|---|---|
| Sandbox base URL | https://test-api.service.hmrc.gov.uk |
| Available in Production | No |
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.
Register for a developer account.
Create an application.
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).
Create a Client ID and Client Secret.
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.
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.
Inject a response using the Common Transit Traders Test Support API. See below.
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.
Endpoints
/test/customs/transits/movements/arrivals/{arrivalId}/messages
/test/customs/transits/movements/departures/{departureId}/messages