Skip to main content

Upload files for large messages

The large message route applies exclusively during the Post-Transition phase.

For each message, you have the option to send it to the NCTS using either the large message route or the small message route. Small messages are limited to 5MB, while large messages can be up to 8MB in size.

For more information about these message routes, see Message sizes.

Submitting a message as a file

Using the large message route means submitting a message as a file in the “application/xml” format, with the file extension .xml.

The following endpoints support submitting a message as a file to the NCTS:

The process of uploading a message is the same for all of the endpoints listed.

To upload a file:

  1. Send a POST request with an empty body and no Content-Type. The API will recognise that you want to upload a file.
  2. The API will respond with a JSON body that contains an uploadRequest object with two fields:
    • href as a string
    • fields as a set of key-value pairs
  3. With a Content-Type of multipart/form-data, send a POST request to the URL returned in the href field with the following payload:
    • each key-value pair in the fields object is its own part, with the name of the part named after the key, and the body of the part containing the value
    • the content of the file added as the last part of the multipart payload, with a name of file and Content-Type of application/xml
  4. Await a push notification from our Push-Pull-Notification Service (PPNS) that will inform you whether your submission succeeded or if errors occurred while processing your message.

An example Python script that submits an IE015 by the large message route is available in this zip file on GitHub.

After the file is submitted, any HTTP 2XX status code will indicate a successful upload.

Tracking progress of messages submitted as files

You can check the progress of the processing status of any message. A submitted message has five possible statuses.

Status Description
Pending The CTC Traders API is waiting for the file to process. It has not yet been submitted or it is awaiting a virus check.
Processing The API has received the file and is processing it.
Success The API processed the message successfully.
Failed The API failed to process the message.
Received This is a message that has been received by HMRC and is intended for a trader. (Although this status is possible, it is not likely to be returned.)

Note: These statuses are applicable only for file submission status.

You can use the following endpoints to get the status of messages submitted to the NCTS:

Push notifications for submitted messages submitted as files

A message submitted by the large message route will receive a push notification of type SUBMISSION_NOTIFICATION when it transitions into the Success or Failed status. If the message failed to send, the error message returned will be identical to that of the small message route. For the Push Pull Notification Service (PPNS), following are the possible statuses

Status Description
PENDING The notification was created but has not been processed.
FAILED The notification was pushed to your Push/Callback URL, but no HTTP status code 200 was returned.
ACKNOWLEDGED The notification was successfully pushed to your Push/Callback URL or you processed the notification using the acknowledge a list of notifications endpoint.

Negative Responses:

{
  "notificationId": "d2369568-1a3a-434c-b61d-e6082d8157d7",
  "boxId": "2c2278ac-5f7a-4796-a903-5e21bea602b7",
  "messageContentType": "application/json",
  "message": {
    "messageUri": "/customs/transits/movements/departures/6627960c3b68bf41/messages/6627960cb6ee7fa1",
    "notificationType": "SUBMISSION_NOTIFICATION",
    "messageId": "6627960cb6ee7fa1",
    "enrollmentEORINumber": "GB006058146075",
    "departureId": "6627960c3b68bf41",
    "response": {
      "message": "Uploaded file not accepted.",
      "code": "BAD_REQUEST"
    }
  },
  "status": "PENDING",
  "createdDateTime": "2024-04-23T11:05:55.011+0000"
}

Positive Response:

{
    "notificationId": "f27719fb-191b-4284-9033-e00c47ed74a5",
    "boxId": "eaa933c4-c62c-4efa-b665-fbfffdbd22b4",
    "messageContentType": "application/json",
    "message": {
        "messageUri": "/customs/transits/movements/departures/6643810d78876593/messages/6643810d1160ed8d",
        "notificationType": "SUBMISSION_NOTIFICATION",
        "messageId": "6643810d1160ed8d",
        "enrollmentEORINumber": "123456",
        "departureId": "6643810d78876593",
        "response": {
            "message": "The message 6643810d1160ed8d for movement 6643810d78876593 was successfully processed",
            "code": "SUCCESS"
        }
    },
    "status": "PENDING",
    "createdDateTime": "2024-05-14T15:26:40.875+0000"
}

For more information about how to receive push notifications, see Push-Pull-Notification Service (PPNS)