This version is in beta - expect some breaking changes.

Safety and security import control entry summary declarations 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 allows you to:

  • create a new ENS submission
  • amend an existing ENS submission

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.

Testing

You can use the sandbox environment to test this API.

Test headers

Additional test support is provided by a number of test headers that can be passed when submitting new or amended ENS declarations.

The following test headers are supported:

simulateRiskingResponse

This header should be used in order for risking simulation to occur so that an outcome (see Safety and Security Import Outcomes) is made available for an ENS submission.

The following values are supported:

Value Description
accept Associate a positive outcome and a Movement Reference Number with an ENS submission (identifiable by its correlation ID).
reject Associate a negative outcome and error details with an ENS submission (identifiable by its correlation ID).


If the header is omitted or has any other value then no risking simulation will be performed and no outcome will be made available for an ENS submission.
If the customs office of first entry <RefNumCUSOFFFENT731> is in Northern Ireland a rejection will be issued regardless of the value of the header.

riskingResponseError

To control the specific error received with a negative outcome when the simulateRiskingResponse header is set to reject.

The following values are supported:

Value Description
nonUniqueLRN Simulates the scenario where the local reference number in the declaration is not unique.
badTransportMode Simulates the scenario where the transport mode is not supported.
badMessageCode Simulates the scenario where the message code is not supported.


If the simulateRiskingResponse header is set to reject but no riskingResponseError header is provided, a default of badTransportMode is assumed.
If the customs office of first entry <RefNumCUSOFFFENT731> is in Northern Ireland a rejection will be issued regardless of the value of the header.

simulateRiskingResponseLatencyMillis

This is used with the simulateRiskingResponse header to provide a delay between the submission of an ENS and the outcome being made available.

The header value is the required simulated latency in milliseconds.

If a value larger than 30000 is supplied, then 30 seconds will be assumed. If the header or value is omitted, then no latency will be simulated.

simulateInterventionResponse

This header should be used in order for intervention simulation to occur so that an advanced notification (see Safety and Security Import Notifications) is made available for an ENS submission.

The header takes the values true or false.

When true, an advanced notification will be associated with an ENS submission (identifiable by its correlation ID).

If the header is omitted or has any other value then no intervention simulation will be performed, and no advanced notification will be made available for an ENS submission.

simulateInterventionResponseLatencyMillis

This is used with the simulateInterventionResponse header to provide a delay between the submission of an ENS and the advanced notification being made available.

The header value is the required simulated latency in milliseconds.

If a value larger than 30000 is supplied, then 30 seconds will be assumed. If the header or value is omitted, then no latency will be simulated.

If you have a specific testing need that is not supported in the sandbox, contact our support team.

Changelog

All service changes can be found within our Wiki page located here.

Skip to main content

Endpoints

/customs/imports/declarations

Submit a new entry summary declaration (ENS)
POST

This endpoint allows a developer to create a new entry summary (IE315) declaration.
A correlation ID is returned in the XML response.

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
Content-Type
required

Specifies the format of the request body, which must be XML.

For example: application/xml; charset=UTF-8
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.

Request

The body of the request must conform to the CC315A schema: http://ics.dgtaxud.ec/CC315A.

This schema imports a number of other schemas:

The body will be validated against this schema and against a number of business rules.

A 400 (Bad Request) response will be returned for requests that fail vaildation. The response body (schema http://www.govtalk.gov.uk/CM/errorresponse) will contain the validation errors found in the request.

This is an example request:

<ie:CC315A xmlns:ie="http://ics.dgtaxud.ec/CC315A">
    <MesSenMES3>GB1234231/1234567890</MesSenMES3>
    <DatOfPreMES9>091231</DatOfPreMES9>
    <TimOfPreMES10>2359</TimOfPreMES10>
    <MesIdeMES19>ABCD1234</MesIdeMES19>
    <MesTypMES20>CC315A</MesTypMES20>
    <HEAHEA>
        <RefNumHEA4>ABCD1234</RefNumHEA4>
        <TraModAtBorHEA76>4</TraModAtBorHEA76>
        <TotNumOfIteHEA305>1</TotNumOfIteHEA305>
        <TotNumOfPacHEA306>1</TotNumOfPacHEA306>
        <TotGroMasHEA307>1.000</TotGroMasHEA307>
        <DecPlaHEA394>EXAMPLE</DecPlaHEA394>
        <ComRefNumHEA>ABC1234D</ComRefNumHEA>
        <ConRefNumHEA>ABC1234D</ConRefNumHEA>
        <PlaLoaGOOITE334>EXAMPLE</PlaLoaGOOITE334>
        <PlaUnlGOOITE334>EXAMPLE</PlaUnlGOOITE334>
        <DecDatTimHEA114>200912312359</DecDatTimHEA114>
    </HEAHEA>
    <TRACONCE1>
        <TINCE159>GBab12</TINCE159>
    </TRACONCE1>
    <GOOITEGDS>
        <IteNumGDS7>1</IteNumGDS7>
        <PRODOCDC2>
            <DocTypDC21>AB12</DocTypDC21>
            <DocRefDC23>ABCDEF123456</DocRefDC23>
        </PRODOCDC2>
        <COMCODGODITM>
            <ComNomCMD1>1234</ComNomCMD1>
        </COMCODGODITM>
        <PACGS2>
            <KinOfPacGS23>VR</KinOfPacGS23>
        </PACGS2>
    </GOOITEGDS>
    <ITI>
        <CouOfRouCodITI1>AB</CouOfRouCodITI1>
    </ITI>
    <ITI>
        <CouOfRouCodITI1>AB</CouOfRouCodITI1>
    </ITI>
    <PERLODSUMDEC>
        <TINPLD1>GBCD12345EFG</TINPLD1>
    </PERLODSUMDEC>
    <CUSOFFFENT730>
        <RefNumCUSOFFFENT731>ABCD1234</RefNumCUSOFFFENT731>
        <ExpDatOfArrFIRENT733>200912312359</ExpDatOfArrFIRENT733>
    </CUSOFFFENT730>
</ie:CC315A>

Response

HTTP status: 200 (OK)

A success response (schema http://www.hmrc.gov.uk/successresponse/2) contains the correlation ID used to track the submission.

This is an example response:

<ns:SuccessResponse xmlns:xd="http://www.w3.org/2000/09/xmldsig#" xmlns:ns="http://www.hmrc.gov.uk/successresponse/2"
                    xmlns="http://www.govtalk.gov.uk/enforcement/ICS/responsedata/7">
    <ns:ResponseData>
        <CorrelationId>87491122139921</CorrelationId>
    </ns:ResponseData>
</ns:SuccessResponse>

Error scenarios

Error scenarios table
Scenario HTTP status Code

The client is not authorised to make the ENS submission. This is normally because the EORI in the submission does not match the EORI under which the trader or CSP has been enroled.

403 (Forbidden)

FORBIDDEN

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


Close Section
/customs/imports/declarations/{movement-reference-number}

Amend an existing entry summary declaration (ENS)
PUT

This endpoint allows a developer to amend an existing ENS submission. You will need to provide the movement reference number when you created the original ENS. A correlation ID will be returned in the XML response.

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
movement-reference-number
string
required

The Movement Reference Number obtained as part of a successful outcome for the ENS to be amended.

Request headers

Request headers Table
Name Description
Content-Type
required

Specifies the format of the request body, which must be XML.

For example: application/xml; charset=UTF-8
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.

Request

The body of the request must conform to the CC313A schema: http://ics.dgtaxud.ec/CC313A.

This schema imports a number of other schemas:

The body will be validated against this schema and against a number of business rules.

A 400 (Bad Request) response will be returned for requests that fail vaildation. The response body (schema http://www.govtalk.gov.uk/CM/errorresponse) will contain the validation errors found in the request.

This is an example request:

<ie:CC313A xmlns:ie="http://ics.dgtaxud.ec/CC313A">
  <MesSenMES3>GBCD1234/1234567890</MesSenMES3>
  <DatOfPreMES9>030211</DatOfPreMES9>
  <TimOfPreMES10>0123</TimOfPreMES10>
  <MesIdeMES19>ABC123</MesIdeMES19>
  <MesTypMES20>CC313A</MesTypMES20>
  <HEAHEA>
    <DocNumHEA5>12AB3C4D5E6F7G8H90</DocNumHEA5>
    <TraModAtBorHEA76>1</TraModAtBorHEA76>
    <IdeOfMeaOfTraCroHEA85>12345678</IdeOfMeaOfTraCroHEA85>
    <TotNumOfIteHEA305>2</TotNumOfIteHEA305>
    <TotNumOfPacHEA306>84</TotNumOfPacHEA306>
    <AmdPlaHEA598>ABC123</AmdPlaHEA598>
    <SpeCirIndHEA1>E</SpeCirIndHEA1>
    <TraChaMetOfPayHEA1>A</TraChaMetOfPayHEA1>
    <ComRefNumHEA>ABC123</ComRefNumHEA>
    <ConRefNumHEA>XFER123-456</ConRefNumHEA>
    <PlaLoaGOOITE334>ABC123</PlaLoaGOOITE334>
    <PlaLoaGOOITE334LNG>en</PlaLoaGOOITE334LNG>
    <PlaUnlGOOITE334>ABC123</PlaUnlGOOITE334>
    <CodPlUnHEA357LNG>en</CodPlUnHEA357LNG>
    <DatTimAmeHEA113>200302111234</DatTimAmeHEA113>
  </HEAHEA>
  <TRACONCO1>
    <NamCO17>ABC123</NamCO17>
    <StrAndNumCO122>ABC123</StrAndNumCO122>
    <PosCodCO123>ABC123</PosCodCO123>
    <CitCO124>ABC123</CitCO124>
    <CouCO125>EN</CouCO125>
    <NADLNGCO>en</NADLNGCO>
  </TRACONCO1>
  <TRACONCE1>
    <TINCE159>GB^</TINCE159>
  </TRACONCE1>
  <GOOITEGDS>
    <IteNumGDS7>1</IteNumGDS7>
    <GooDesGDS23>ABC123</GooDesGDS23>
    <SPEMENMT2>
      <AddInfCodMT23>12345</AddInfCodMT23>
    </SPEMENMT2>
    <PACGS2>
      <KinOfPacGS23>AA</KinOfPacGS23>
      <NumOfPacGS24>42</NumOfPacGS24>
      <MarNumOfPacGSL21>ABC123</MarNumOfPacGSL21>
      <MarNumOfPacGSL21LNG>en</MarNumOfPacGSL21LNG>
    </PACGS2>
  </GOOITEGDS>
  <GOOITEGDS>
    <IteNumGDS7>2</IteNumGDS7>
    <GooDesGDS23>ABC123</GooDesGDS23>
    <SPEMENMT2>
      <AddInfCodMT23>12345</AddInfCodMT23>
    </SPEMENMT2>
    <PACGS2>
      <KinOfPacGS23>AA</KinOfPacGS23>
      <NumOfPacGS24>42</NumOfPacGS24>
      <MarNumOfPacGSL21>ABC123</MarNumOfPacGSL21>
      <MarNumOfPacGSL21LNG>en</MarNumOfPacGSL21LNG>
    </PACGS2>
  </GOOITEGDS>
  <ITI>
    <CouOfRouCodITI1>EN</CouOfRouCodITI1>
  </ITI>
  <ITI>
    <CouOfRouCodITI1>EN</CouOfRouCodITI1>
  </ITI>
  <PERLODSUMDEC>
    <TINPLD1>GBABC</TINPLD1>
  </PERLODSUMDEC>
  <CUSOFFFENT730>
    <RefNumCUSOFFFENT731>AB3C4D5F</RefNumCUSOFFFENT731>
    <ExpDatOfArrFIRENT733>200302111234</ExpDatOfArrFIRENT733>
  </CUSOFFFENT730>
</ie:CC313A>

Response

HTTP status: 200 (OK)

A success response (schema http://www.hmrc.gov.uk/successresponse/2) contains the correlation ID used to track the submission.

This is an example response:

<ns:SuccessResponse xmlns:xd="http://www.w3.org/2000/09/xmldsig#" xmlns:ns="http://www.hmrc.gov.uk/successresponse/2"
                    xmlns="http://www.govtalk.gov.uk/enforcement/ICS/responsedata/7">
    <ns:ResponseData>
        <CorrelationId>87491122139921</CorrelationId>
    </ns:ResponseData>
</ns:SuccessResponse>

Error scenarios

Error scenarios table
Scenario HTTP status Code

The client is not authorised to make the ENS submission. This is normally because the EORI in the submission does not match the EORI under which the trader or CSP has been enroled.

403 (Forbidden)

FORBIDDEN

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


Close Section

Skip to main content