Customs Inventory Linking Exports 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
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.
ZIP, 2.2MB last updated 16/03/2023
The ZIP file contains XML files. Open in your preferred file viewer.
Endpoints
/customs/inventory-linking/exports
Inventory Exports Request
POST
Submit an Inventory Exports Request
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the version of the API that you want to call. See versioning. application/vnd.hmrc.1.0+xml
|
Content-Type
required
|
Specifies the format of the request body, which must be XML. 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. 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. 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