This version is in beta - expect some breaking changes.

Safety and security import control entry summary declaration outcomes API

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.

Skip to main content

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.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:import-control-system scope.

Request headers

Name	Description
Accept required	Specifies the response format and the version of the API to be used. For example: 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.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:import-control-system scope.

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. For example: 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.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:import-control-system scope.

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. For example: 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

Skip to main content

Is this page not working properly? (opens in new tab)