This version is in beta - expect some breaking changes.
Customs Declarations API
|Available in Sandbox||Yes|
|Sandbox base URL||https://test-api.service.hmrc.gov.uk|
|Available in Production||No|
This API allows the submission of any UCC declarations for asynchronous processing by the customs declarations service, to enable a user to have their declarations accepted by means of a single API.
The API takes any UCC declaration payload. It also allows for the submission of a cancellation request (pre-clearance) and provides a method of securely uploading additional documentation to support a declaration submission.
This service is used to initiate a file upload as part of the declaration submission process. An example document you may be requested to upload could be a paper copy of a licence. This endpoint is used to initiate a file upload where a signed URL is returned by the endpoint to be used in the file upload workflow.
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.
We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:
- 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
- 400 to 499 if it failed because of a client error by your application
- 500 to 599 if it failed because of an error on our server
Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.
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
- 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 (Please Ignore this EORI, only use the EORI that has been assigned to you for TT).
- After completing the above, if you call the Customs Declaration 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.