Safety and security import control entry summary declaration outcomes API
Date | Amount |
---|---|
Version and status | |
Available in Sandbox | Yes |
Sandbox base URL | https://test-api.service.hmrc.gov.uk |
Available in Production | Yes |
Production base URL | https://api.service.hmrc.gov.uk |
Overview
The Safety and Security system handles digital communications between:
- customs administrators
- carriers or their appointed representatives
You must provide the UK customs authorities with advance information by submitting an ENS before you bring goods into the UK. The Safety and Security system is designed to incorporate the:
- lodging, handling and processing of the ENS in advance of the arrival of goods
- issuing of a Movement Reference Number (MRN)
The MRN is a Customs computer system-generated number that is automatically allocated after successful validation. The MRN must be issued to the carrier and, where different, the declarant.
The APIs will receive new ENS submissions or amendments and will return a response for the end-user. The response will include a movement reference number or an error message.
This API will allow you to:
- get a list of outcomes
- retrieve an outcome
- acknowledge an outcome
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
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.
Changelog
All service changes can be found within our Wiki page located here.
Endpoints
/customs/imports/outcomes
Get a list of outcomes
GET
This endpoint allows a developer to get a list of outcomes for submissions that are yet to be acknowledged.
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.1.0+xml
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:import-control-system scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
A list of Correlation IDs for unacknowledged outcomes (schema here). These Correlation IDs correspond to values returned in responses to previously submitted ENS declarations.
Outcomes that are successful (accepted) will have a Movement Reference Number (MRN) associated with the Correlation ID in the XML. Outcomes that are unsuccessful (rejected) will have no Movement Reference Number.
A maximum of 100 outcomes will be returned in each response.
This is an example response:
<entryDeclarationResponses> <response> <correlationId>1234567890</correlationId> <link>/customs/imports/outcomes/1234567890</link> <MRN>1234567890</MRN> </response> <response> <correlationId>0987654321</correlationId> <link>/customs/imports/outcomes/0987654321</link> </response> </entryDeclarationResponses>
HTTP status 204 (No Content)
There are no outcomes available.
Close Section
/customs/imports/outcomes/{correlationId}
Retrieve an outcome
GET
This endpoint allows a developer to get the outcome for given Correlation ID.
Path parameters
Name | Description |
---|---|
correlationId
string
required
|
The Correlation ID corresponding to an ENS declaration.
|
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.1.0+xml
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:import-control-system scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
The outcome for the Correlation ID (schema here).
An accepted outcome which is successful will contain a Movement Reference Number. A rejected outcome will contain one or more errors. Accordingly, the content of response element will be based on one of the following schemas:
- New submission accepted: schema http://ics.dgtaxud.ec/CC328A.
- New submission rejected: schema http://ics.dgtaxud.ec/CC316A.
- Amended submission accepted: schema http://ics.dgtaxud.ec/CC304A.
- Amended submission rejected: schema http://ics.dgtaxud.ec/CC305A.
These schemas import a number of other schemas:
- http://ics.dgtaxud.ec/doc
- http://ics.dgtaxud.ec/complex_ics
- http://ics.dgtaxud.ec/simple
- http://ics.dgtaxud.ec/simple_ics
- http://ics.dgtaxud.ec/tcl
- http://ics.dgtaxud.ec/tcl_ics
This is an example response:
<outcomeResponse xmlns:cc3="http://ics.dgtaxud.ec/CC328A"> <response> <cc3:CC328A> <MesSenMES3>GB000012340003/1234567890</MesSenMES3> <MesRecMES6>GB000012340003/1234567890</MesRecMES6> <DatOfPreMES9>190114</DatOfPreMES9> <TimOfPreMES10>0945</TimOfPreMES10> <MesIdeMES19>MSUI11235227</MesIdeMES19> <MesTypMES20>CC328A</MesTypMES20> <CorIdeMES25>0JRF7UncK0t004</CorIdeMES25> <HEAHEA> <RefNumHEA4>Preeti_315A_TC001</RefNumHEA4> <DocNumHEA5>10GB08I01234567891</DocNumHEA5> <DecRegDatTimHEA115>201901140945</DecRegDatTimHEA115> </HEAHEA> <CUSOFFLON> <RefNumCOL1>ES000055</RefNumCOL1> </CUSOFFLON> <PERLODSUMDEC> <TINPLD1>GB000012340002</TINPLD1> </PERLODSUMDEC> <CUSOFFFENT730> <RefNumCUSOFFFENT731>GB000011</RefNumCUSOFFFENT731> </CUSOFFFENT730> </cc3:CC328A> </response> <acknowledgement method='DELETE' href='/customs/imports/outcomes/0JRF7UncK0t004'/> </outcomeResponse>
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
No outcome for the submission with the specified Correlation ID is currently available or the outcome has already been acknowledged. |
404 (Not Found) |
OUTCOME_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Close Section
/customs/imports/outcomes/{correlationId}
Acknowledge an outcome
DELETE
This endpoint allows a developer to acknowledge an outcome using a given correlation ID. After calling this endpoint the outcome will no longer be retrievable and will no longer appear in the list of outcomes.
Path parameters
Name | Description |
---|---|
correlationId
string
required
|
The Correlation ID corresponding to an ENS declaration.
|
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the response format and the version of the API to be used. application/vnd.hmrc.1.0+xml
|
Authorization
required
|
An
OAuth 2.0 Bearer Token
with the write:import-control-system scope.
For example: Bearer bb7fed3fe10dd235a2ccda3d50fb
|
See also fraud prevention.
Responses
HTTP status 200 (OK)
The outcome has successfully been acknowledged.
Error scenarios
Scenario | HTTP status | Code |
---|---|---|
No outcome for the submission with the specified Correlation ID is currently available or the outcome has already been acknowledged. |
404 (Not Found) |
OUTCOME_NOT_FOUND |
For error scenarios that are common across all APIs, and for error formats, see our reference guide.
Close Section