This version is in beta - expect some breaking changes.

Safety and security import control entry summary declaration notifications API

Dates and amounts
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 notifications
  • retrieve a notification
  • acknowledge a notification

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/notifications

Get a list of notifications
GET

This endpoint allows a developer to retrieve a list of advanced notifications 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

Request headers Table
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.

Response

HTTP status: 200 (OK)

The response will contain a list (schema here) of Notication IDs corresponding to advanced notifications for ENS submissions. Each one will be listed along with the Correlation ID that identifies the submission.

The list will include only those notifications that have not been acknowledged.

This is an example response:

<advancedNotifications>
  <response>
    <correlationId>1234567890</correlationId>
    <notificationId>1D45fQ563</notificationId>
    <link>/customs/imports/notifications/1D45fQ563</link>
  </response>
  <response>
    <correlationId>0987654321</correlationId>
    <notificationId>ABx4414f4</notificationId>
    <link>/customs/imports/notifications/ABx4414f4</link>
  </response>
</advancedNotifications>

Response

HTTP status: 204 (No Content)

There are no notifications available.


                


Close Section
/customs/imports/notifications/{notificationId}

Retrieve a notification
GET

This endpoint allows a developer to retrieve an advanced notification for a given Notification 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

Path parameters table
Name Description
notificationId
string
required

The Notification ID that uniquely identifies the notification.

Request headers

Request headers Table
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.

Response

HTTP status: 200 (OK)

A notification for the Notification ID (schema here).

The content of response element will be determined by the type of notification. Currently the following types of notification can be returned:

This schema imports a number of other schemas:

This is an example response:

<notificationResponse xmlns:cc3="http://ics.dgtaxud.ec/CC351A">
    <response>
        <cc3:CC351A>
            <MesSenMES3>GBCD1234/1234567890</MesSenMES3>
            <MesRecMES6>GBC123</MesRecMES6>
            <DatOfPreMES9>030211</DatOfPreMES9>
            <TimOfPreMES10>0123</TimOfPreMES10>
            <MesIdeMES19>ABC123</MesIdeMES19>
            <MesTypMES20>CC313A</MesTypMES20>
            <CorIdeMES25>ABC123</CorIdeMES25>
            <HEAHEA>
                <RefNumHEA4>ABCD1234</RefNumHEA4>
                <DocNumHEA5>12AB3C4D5E6F7G8H90</DocNumHEA5>
                <TraModAtBorHEA76>4</TraModAtBorHEA76>
                <NatHEA001>GB</NatHEA001>
                <IdeOfMeaOfTraCroHEA85>ABC123</IdeOfMeaOfTraCroHEA85>
                <TotNumOfIteHEA305>42</TotNumOfIteHEA305>
                <ComRefNumHEA>ABC123</ComRefNumHEA>
                <ConRefNumHEA>ABC123</ConRefNumHEA>
                <NotDatTimHEA104>200302111234</NotDatTimHEA104>
                <DecRegDatTimHEA115>200302111234</DecRegDatTimHEA115>
                <DecSubDatTimHEA118>200302111234</DecSubDatTimHEA118>
            </HEAHEA>
            <GOOITEGDS>
                <IteNumGDS7>1</IteNumGDS7>
                <ComRefNumGIM1>ABC123</ComRefNumGIM1>
                <PRODOCDC2>
                    <DocTypDC21>AB12</DocTypDC21>
                    <DocRefDC23>ABC123</DocRefDC23>
                    <DocRefDCLNG>en</DocRefDCLNG>
                </PRODOCDC2>
                <CONNR2>
                    <ConNumNR21>ABC123</ConNumNR21>
                </CONNR2>
                <IDEMEATRAGI970>
                    <NatIDEMEATRAGI973>EN</NatIDEMEATRAGI973>
                    <IdeMeaTraGIMEATRA971>ABC123</IdeMeaTraGIMEATRA971>
                    <IdeMeaTraGIMEATRA972LNG>en</IdeMeaTraGIMEATRA972LNG>
                </IDEMEATRAGI970>
            </GOOITEGDS>
            <CUSOFFLON>
                <RefNumCOL1>ES000055</RefNumCOL1>
            </CUSOFFLON>
            <TRAREP>
                <NamTRE1>ABC123</NamTRE1>
                <StrAndNumTRE1>ABC123</StrAndNumTRE1>
                <PosCodTRE1>ABC123</PosCodTRE1>
                <CitTRE1>ABC123</CitTRE1>
                <CouCodTRE1>EN</CouCodTRE1>
                <TRAREPLNG>en</TRAREPLNG>
                <TINTRE1>YZ^</TINTRE1>
            </TRAREP>
            <PERLODSUMDEC>
                <NamPLD1>ABC123</NamPLD1>
                <StrAndNumPLD1>ABC123</StrAndNumPLD1>
                <PosCodPLD1>ABC123</PosCodPLD1>
                <CitPLD1>ABC123</CitPLD1>
                <CouCodPLD1>EN</CouCodPLD1>
                <PERLODSUMDECLNG>en</PERLODSUMDECLNG>
                <TINPLD1>YZ^</TINPLD1>
            </PERLODSUMDEC>
            <CUSOFFFENT730>
                <RefNumCUSOFFFENT731>AB3C4D5E</RefNumCUSOFFFENT731>
                <ExpDatOfArrFIRENT733>200302111234</ExpDatOfArrFIRENT733>
            </CUSOFFFENT730>
            <TRACARENT601>
                <NamTRACARENT604>ABC123</NamTRACARENT604>
                <StrNumTRACARENT607>ABC123</StrNumTRACARENT607>
                <PstCodTRACARENT606>ABC123</PstCodTRACARENT606>
                <CtyTRACARENT603>ABC123</CtyTRACARENT603>
                <CouCodTRACARENT605>EN</CouCodTRACARENT605>
                <TRACARENT601LNG>en</TRACARENT601LNG>
                <TINTRACARENT602>YZ^</TINTRACARENT602>
            </TRACARENT601>
            <CUSINT632>
                <IteNumConCUSINT668>1</IteNumConCUSINT668>
                <CusIntCodCUSINT665>ABCD</CusIntCodCUSINT665>
                <CusIntTexCUSINT666>ABC12</CusIntTexCUSINT666>
                <CusIntTexCUSINT667LNG>en</CusIntTexCUSINT667LNG>
            </CUSINT632>
        </cc3:CC351A>
    </response>
    <acknowledgement method='DELETE' href='/customs/imports/notifications/0JRF7UncK0t004'/>
</notificationResponse>

Error scenarios

Error scenarios table
Scenario HTTP status Code

No notification for the submission with the specified Notification ID is currently available or the notification has already been acknowledged.

404 (Not Found)

NOTIFICATION_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section
/customs/imports/notifications/{notificationId}

Acknowledge a notification
DELETE

This endpoint allows a developer to acknowledge the receipt of an advanced notification for a given Notification 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

Path parameters table
Name Description
notificationId
string
required

The Notification ID that uniquely identifies the notification.

Request headers

Request headers Table
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.

Response

HTTP status: 200 (OK)

The notification has successfully been acknowledged.


                

Error scenarios

Error scenarios table
Scenario HTTP status Code

No notification for the submission with the specified Notification ID is currently available or the notification has already been acknowledged.

404 (Not Found)

NOTIFICATION_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