Appendix
Message sizes
The CTC Traders API (any version) supports two routes for transmitting messages to the NCTS. Traders may select, on a per-message basis, either the large message route or the small message route for sending messages.
Differences between large and small message routes
The following table summarises the main differences between the large and small routes supported by the API.
| Attribute | Large message route | Small message route |
|---|---|---|
| Message size limit | 8MB | 5MB |
| Submission type | File-based | Direct |
| Messaging type | Asynchronous | Synchronous |
| Successful message | Near real time (with push notifications) | Immediate submission feedback |
| Timeout resilience | Strong | Weak |
| Transit size (average) | Large | Small |
Determining Which Message Route to Use
Traders handling transit movements with large consignments should consider using the large message route. Before finalizing how application software will manage message sizes, the following factors should be evaluated:
- The large message route supports both large and small messages, but only the POST endpoints of the CTC Traders API accommodate the large message route, while all GET endpoints can process messages of any size.
- For traders or those they serve, prioritizing quick response times from the NCTS, and whose message sizes do not exceed 5MB, the small message functionality of the API should be used exclusively.
When opting for the large message route, traders may leverage the Push Pull Notifications API to receive automatic notifications from the NCTS in near real-time.
Sending Large Messages
To transmit a transit declaration via the large message route, traders must call the API with an empty payload. A successful response will include:
- A URL and additional metadata required for uploading the file.
- A message ID to track the status of the specific message.
For further details on sending large messages, refer to the Upload Files for Large Messages documentation.
Developer Setup
Developing with CTC Traders API
To develop using the CTC Traders API, traders or their software providers must:
- Possess familiarity with HTTP, RESTful services, XML, and OAuth2.
- Register as a developer on the HMRC Developer Hub.
- Create at least one sandbox application on the Developer Hub.
Each registered application will receive a unique HMRC ApplicationId. All registered applications can be viewed and managed on the Developer Hub Applications page, where API subscriptions and application credentials can be administered.
Applications may be created in one of two environments:
- Sandbox Environment: Used for initial development and testing of software.
- Production Environment: Upon readiness to go live, request ‘Production Credentials’ to create a new application (with a new ApplicationId) in the production environment.
Key differences between the two environments include:
- In the sandbox environment, test users must be created and used to call the API endpoints.
- The release version of an API in the sandbox is typically ahead of the version in the production environment.
The sandbox environment (also known as External Test) serves as an HMRC platform for external partners to complete required assurance activities, ensuring confidence in their readiness for migration to NCTS.
For further details on utilizing sandbox environments, refer to the Testing in the Sandbox documentation.