Customs Declarations Information API
| REST | |
| Version 2.0 - beta | |
| 27 May 2026 | |
| Sandbox base URL | https://test-api.service.hmrc.gov.uk |
| Production base URL | https://api.service.hmrc.gov.uk |
Overview
Use this API to search for and get details of a customs declaration.
Service features
This API is currently in beta - expect some breaking changes.
This API does not support spaces.
Endpoints provided by this service are:
- search for a declaration based on role, category, date, goods location code and status.
- get the status of a declaration by MRN, DUCR, UCR or inventory reference
- get a list of versions of a declaration by MRN
- get a full declaration by MRN and, optionally, by version
Data availability
Only declarations received by CDS in the last 180 days will be returned by this API.
Declaration Status Endpoints
The status endpoints return a response that can contain the following fields:
| AcceptanceDateTime/DateTimeString | Date and time on which the declaration was legally accepted.
This is only populated on an arrived declaration. |
| ID | Movement Reference Number (MRN) |
| VersionID | Declaration version number. This will be the latest version. |
| ReceivedDateTime/DateTimeString | Date and time on which the declaration was received |
| GoodsReleasedDateTime/DateTimeString | Date and time on which the goods were released. |
| ROE | Customs route of entry. |
| ICS | Import clearance status. |
| IRC | Inventory return code. This is the error response from inventory linking |
| FunctionCode | Function code is always set to 9. |
| TypeCode | Declaration type. UCC data elements 1/1 + 1/2. |
| GoodsItemQuantity | Total number of items. UCC data element 1/9. |
| TotalPackageQuantity | Total number of packages. UCC data element 6/18. |
| Submitter/ID | Submitting Trader. This is the ID of the initiating trader if the declaration is submitted via a CSP. |
| GoodsShipment/PreviousDocument/ID | The ID of a previous document. A DUCR or MUCR. |
| GoodsShipment/PreviousDocument/TypeCode | The type of a previous document: DCR = DUCR MCR = MUCR |
| GoodsShipment/UCR/TraderAssignedReferenceID | Reference Number or UCR. UCC data element 2/4. |
Please note that not all of these fields are guaranteed to be present for every declaration returned.
Declaration Version Endpoint
The version endpoint returns a response that can contain the following fields:
| ID | Movement Reference Number (MRN). |
| VersionID | Declaration version number. |
| CreatedDateTime/DateTimeString | Date and time on which the declaration version was created. |
| LRN | Local reference number. |
| FunctionCode | Function code is always set to 9. |
| TypeCode | Declaration type. UCC data elements 1/1 + 1/2. |
| GoodsShipment/Consignment/GoodsLocation/Name | Name of the place where goods are located. |
| GoodsShipment/Consignment/GoodsLocation/TypeCode | Goods location type code. |
| GoodsShipment/Consignment/GoodsLocation/Address/TypeCode | Type of address. |
| GoodsShipment/Consignment/GoodsLocation/Address/CountryCode | Country code of address. |
| GoodsShipment/PreviousDocument/ID | The ID of a previous document. A DUCR or MUCR. |
| GoodsShipment/PreviousDocument/TypeCode | The type of a previous document. |
Full Declaration Endpoint
See the schema file, DeclarationInformationRetrievalFullResponse.xsd, in the download zip for the documentation on the fields returned in the response.
Search Declarations Endpoint
See the schema file, DeclarationInformationRetrievalSearchResponse.xsd, in the download zip for the documentation on the fields returned in the response.
Please note that not all the fields documented here and in the schema files are guaranteed to be present for every declaration returned.
API authorisation
Only the authorised API users can query the status, search or get versions of a declaration.
Errors
We use standard HTTP status codes to show whether an API request succeeded or not.
Status endpoint error scenarios
| Scenario | HTTP Status | Code | Message |
| Declaration not found for given MRN, DUCR, UCR or Inventory Reference | 404 (Not Found) | CDS60001 | Declaration not found |
| Invalid MRN, DUCR, UCR or Inventory Reference | 400 (Bad Request) | CDS60002 | Search parameter invalid |
| Missing MRN, DUCR, UCR or Inventory Reference | 400 (Bad Request) | BAD_REQUEST | Missing search parameter |
| MRN, DUCR, UCR or Inventory Reference too long | 400 (Bad Request) | BAD_REQUEST | Search parameter too long |
| For CSPs only, X-Submitter-Identifier and X-Badge-Identifier http headers are missing | 400 (Bad Request) | BAD_REQUEST | Both X-Submitter-Identifier and X-Badge-Identifier headers are missing |
| For CSPs only, X-Submitter-Identifier is invalid | 400 (Bad Request) | BAD_REQUEST | X-Submitter-Identifier header is invalid |
| For CSPs only, X-Submitter-Identifier header is invalid | 400 (Bad Request) | BAD_REQUEST | X-Badge-Identifier header is invalid |
| A firewall rejected the request | 403 (Payload Forbidden) | PAYLOAD_FORBIDDEN | A firewall rejected the request |
| Internal server error | 500 | CDS60003 or INTERNAL_SERVER_ERROR | Internal server error |
Version endpoint error scenarios
| Scenario | HTTP Status | Code | Message |
| Declaration not found for given MRN | 404 (Not Found) | CDS60001 | Declaration not found |
| Invalid MRN | 400 (Bad Request) | CDS60002 | MRN parameter invalid |
| Missing MRN | 400 (Bad Request) | BAD_REQUEST | Missing MRN parameter |
| MRN too long | 400 (Bad Request) | BAD_REQUEST | MRN parameter too long |
| For CSPs only, X-Submitter-Identifier and X-Badge-Identifier http headers are missing | 400 (Bad Request) | BAD_REQUEST | Both X-Submitter-Identifier and X-Badge-Identifier headers are missing |
| For CSPs only, X-Submitter-Identifier is invalid | 400 (Bad Request) | BAD_REQUEST | X-Submitter-Identifier header is invalid |
| For CSPs only, X-Submitter-Identifier header is invalid | 400 (Bad Request) | BAD_REQUEST | X-Badge-Identifier header is invalid |
| A firewall rejected the request | 403 (Payload Forbidden) | PAYLOAD_FORBIDDEN | A firewall rejected the request |
| Internal server error | 500 | CDS60003 or INTERNAL_SERVER_ERROR | Internal server error |
Full endpoint error scenarios
| Scenario | HTTP Status | Code | Message |
| Declaration not found for given MRN | 404 (Not Found) | CDS60001 | Declaration not found |
| Invalid MRN | 400 (Bad Request) | CDS60002 | MRN parameter invalid |
| Missing MRN | 400 (Bad Request) | BAD_REQUEST | Missing MRN parameter |
| MRN too long | 400 (Bad Request) | BAD_REQUEST | MRN parameter too long |
| Invalid declarationVersion parameter | 400 | BAD_REQUEST | Invalid declarationVersion parameter |
| For CSPs only, X-Submitter-Identifier and X-Badge-Identifier http headers are missing | 400 (Bad Request) | BAD_REQUEST | Both X-Submitter-Identifier and X-Badge-Identifier headers are missing |
| For CSPs only, X-Submitter-Identifier is invalid | 400 (Bad Request) | BAD_REQUEST | X-Submitter-Identifier header is invalid |
| For CSPs only, X-Submitter-Identifier header is invalid | 400 (Bad Request) | BAD_REQUEST | X-Badge-Identifier header is invalid |
| A firewall rejected the request | 403 (Payload Forbidden) | PAYLOAD_FORBIDDEN | A firewall rejected the request |
| Internal server error | 500 | CDS60003 or INTERNAL_SERVER_ERROR | Internal server error |
Search endpoint error scenarios
| Scenario | HTTP Status | Code | Message |
| For CSPs only, X-Submitter-Identifier and X-Badge-Identifier http headers are missing | 400 (Bad Request) | BAD_REQUEST | Both X-Submitter-Identifier and X-Badge-Identifier headers are missing |
| For CSPs only, X-Submitter-Identifier is invalid | 400 (Bad Request) | BAD_REQUEST | X-Submitter-Identifier header is invalid |
| For CSPs only, X-Submitter-Identifier header is invalid | 400 (Bad Request) | BAD_REQUEST | X-Badge-Identifier header is invalid |
| Internal server error | 500 | CDS60003 or INTERNAL_SERVER_ERROR | Internal server error |
| Page number is out of bounds | 400 (Bad Request) | CDS60005 | pageNumber parameter out of bounds |
| Invalid declarationStatus parameter | 400 (Bad Request) | CDS60006 | Invalid declarationStatus parameter |
| Invalid declarationStatus parameter | 400 (Bad Request) | CDS60007 | Invalid declarationStatus parameter |
| Invalid declarationCategory parameter | 400 (Bad Request) | CDS60008 | Invalid declarationCategory parameter |
| Invalid date parameters | 400 (Bad Request) | CDS60009 | Invalid date parameters |
| Invalid goodsLocationCode parameter | 400 (Bad Request) | CDS60010 | Invalid goodsLocationCode parameter |
| Invalid pageNumber parameter | 400 (Bad Request) | CDS60012 | Invalid pageNumber parameter |
| A firewall rejected the request | 403 (Payload Forbidden) | PAYLOAD_FORBIDDEN | A firewall rejected the request |
See our reference guide for more on errors.
Testing
You can use the HMRC Developer Sandbox to test the Customs Declarations API. The Sandbox is an enhanced testing service that functions as a simulator of HMRC’s production environment. To use the Customs Declaration API you will need to create your own test user. To create your own test user:
- Use the Create Test User API
- Ensure under ‘Body’ “customs-services” is requested. To use an EORI from the Test Data Library, provide it as part of the request.
- The first time you call this API the username and password log in box should appear (select do not have credentials, follow the steps & enter the username/password provided).
- If successful this will prompt the grant authority to your application and select approve. If correct, you should see a 200 response showing some test data including a username, password and EORI.
- After completing the above, if you call the Customs Declarations Information API, the same process should occur whereby it will ask for a username and password (Please enter the Username and Password that is in the test data generated from the step above when calling the create test user API) Please Note: 443 is the only allowed port, which means port 443 will need to be used in the callback URL.
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.
Endpoints
| Version | Environments | Endpoints |
|---|---|---|
|
Version 2.0 - beta
(opens in new tab) |
Sandbox | 2.0 endpoints |
|
Version 1.0 - beta
(opens in new tab) |
Sandbox and Production | 1.0 endpoints |