This version is in beta - expect some breaking changes.

Customs Inventory Linking Exports 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

This API enables the functionality to support the Inventory Linking Export process. Inventory Linking controls and monitors cargo moving through temporary storage facilities, and allows the movement/transition through frontiers.

There are three functional areas;

• Consolidation This enables the combining of consignments into one master consignment, or splitting into multiple consignments.
• Movement Records the movement of consignments within Customs controlled storage facilities.
• Query The querying of data held within the Inventory Linking Export database.

Within each of these functional areas, there are multiple message types, each performing a specific activity.

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.

XML Schemas

Schema definitions for all the API endpoints request and response payloads can be found in the following zip archive.

Schemas and example messages

ZIP, 2.2MB last updated 16/03/2023

The ZIP file contains XML files. Open in your preferred file viewer.

Skip to main content

Endpoints

/customs/inventory-linking/exports

Inventory Exports Request

POST

Submit an Inventory Exports Request

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:customs-inventory-linking-exports scope.

Request headers

Name	Description
Accept required	Specifies the version of the API that you want to call. See versioning. For example: application/vnd.hmrc.1.0+xml
Content-Type required	Specifies the format of the request body, which must be XML. For example: application/xml; charset=UTF-8
X-Badge-Identifier optional	Represents the end-user who is interacting with the subscribed application. Must be 6 to 12 characters, consisting of any combination of numeric digits and/or upper-case letters. For example: ABC123
X-Submitter-Identifier optional	The EORI associated with the originating owner of the declaration. Must have a maximum length of 17 characters, consisting of any combination of numeric digits and/or letters. For example: ABC123
Authorization required	An OAuth 2.0 Bearer Token with the write:customs-inventory-linking-exports scope. For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

<?xml version="1.0" encoding="UTF-8"?>
<!-- CST – A Consolidation message is used to shut MUCR prior to departure -->
<inv:inventoryLinkingConsolidationRequest xmlns:inv="http://gov.uk/customs/inventoryLinking/v1">
  <inv:messageCode>CST</inv:messageCode>
  <!--Maritime MUCR assigned to the consignment. Arriving at MUCR level. This value has come from Declaration -->
  <inv:masterUCR>GB/123456789012-0203N1</inv:masterUCR>
</inv:inventoryLinkingConsolidationRequest>

Request

<?xml version="1.0" encoding="UTF-8"?>
<!-- EAL – Movement message notification format for Entry arriving at location (Arrivals) -->
<inv:inventoryLinkingMovementRequest xmlns:inv="http://gov.uk/customs/inventoryLinking/v1">
                   <inv:messageCode>EAL</inv:messageCode>
				   <inv:ucrBlock>
				   <!--Air time MUCR assigned to the consignment. Arriving at MUCR level. This value has come from Declaration -->
                    <inv:ucr>GB/123456789012-0203N1</inv:ucr>
                        <inv:ucrType>M</inv:ucrType>
                   </inv:ucrBlock>
				   <!-- ID to give a unique position of the location. DVRDOVDVR Indicating Dover. This value has come from Declaration -->
                   <inv:goodsLocation>GBAUDVRDOVDVR</inv:goodsLocation>
				   <!-- This should be today's Date -->
                   <inv:goodsArrivalDateTime>2021-03-09T08:00:00</inv:goodsArrivalDateTime>
                    <inv:movementReference>Movement14</inv:movementReference>
								<inv:transportDetails>
                      <inv:transportID>11CSCLGLOBE</inv:transportID>
                      <inv:transportMode>1</inv:transportMode>
                      <inv:transportNationality>GB</inv:transportNationality>
                   </inv:transportDetails>
</inv:inventoryLinkingMovementRequest>

Request

<?xml version="1.0" encoding="UTF-8"?>
<inv:inventoryLinkingQueryRequest xmlns:inv="http://gov.uk/customs/inventoryLinking/v1">
    <inv:queryUCR>
        <inv:ucr>GB/AAAA-00000</inv:ucr>
        <inv:ucrPartNo>123A</inv:ucrPartNo>
        <inv:ucrType>D</inv:ucrType>
    </inv:queryUCR>
</inv:inventoryLinkingQueryRequest>

Responses

HTTP status 202 (Accepted)

HTTP status 400 (Bad Request)

<?xml version="1.0" encoding="UTF-8"?>
<errorResponse>
    <code>BAD_REQUEST</code>
    <message>Payload is not valid according to schema</message>
    <errors>
        <error>
            <code>xml_validation_error</code>
            <message>Error at line 13, column 13: no declaration found for element 'unknown'</message>
        </error>
    </errors>
</errorResponse>

HTTP status 406 (Not Acceptable)

<?xml version="1.0" encoding="UTF-8"?>
<errorResponse>
  <code>ACCEPT_HEADER_INVALID</code>
  <message>The accept header is missing or invalid</message>
</errorResponse>

HTTP status 415 (Unsupported Media Type)

<?xml version="1.0" encoding="UTF-8"?>
<errorResponse>
  <code>UNSUPPORTED_MEDIA_TYPE</code>
  <message>The content type header is missing or invalid</message>
</errorResponse>

HTTP status 500 (Internal Server Error)

<?xml version="1.0" encoding="UTF-8"?>
<errorResponse>
    <code>INTERNAL_SERVER_ERROR</code>
    <message>Internal server error</message>
</errorResponse>

Error scenarios

Scenario	HTTP status	Code
Invalid XML Payload	400 (Bad Request)	BAD_REQUEST
Invalid Accept header	406 (Not Acceptable)	ACCEPT_HEADER_INVALID
Invalid Content-type header	415 (Unsupported Media Type)	UNSUPPORTED_MEDIA_TYPE
Internal server error	500 (Internal Server Error)	INTERNAL_SERVER_ERROR

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)