Import Control Presentation of Goods API
| 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 provides resources related to the Import Control System Presentation of Goods service.
Once Goods have arrived in Northern Ireland, the Presentation of Goods Service will allow your users to do the following:
the person who will be presenting goods will submit a Presentation Notification to Customs, which includes details relevant to all goods available for presentation
where Customs have been advised that goods need intervention the person presenting the goods will receive a Control Notification confirming which goods require intervention checks and the date and time where the goods need to be presented for inspection
where Customs have been advised that the goods do not need to be controlled, a Control Notification will not be sent to the person presenting the goods
To learn more, read the Presentation of Goods Service Guide
Authorisation
The endpoint in this API is user-restricted. Your users must grant authority for your software to access it by signing in to their HMRC online account.
The API supports organisation users only.
Notifications
Push Pull Notifications Service (PPNS)
In response to submitting a Presentation Notification, Customs may provide a Control Notification of the outcome via the PPNS API.
These notifications can be delivered:
if the user has set the callback URL during subscription to PPNS in the Subscription configuration field of their application, notifications will be pushed to the callback URL.
if the callback URL is not set, the user can call the PPNS GET endpoint to pull the notification.
Providing both options to receive notifications will help users specifically in error scenarios when repeated attempts for sending a message to a callback url is failing. In such situations users can retrieve messages from the assigned PPNS box using the Pull Notification method.
PPNS Box Id
When a Presentation Notification is submitted to the Import Control Presentation of Goods API, the user will receive a 202 Accepted response and the PPNS Box Id. For example:
{
"boxId": "50dca3fc-c37c-4f03-b719-63571333624c"
}
The boxId is specific to PPNS and your application. All your Control Notifications will be sent to the same boxId. Other applications will not be able to access these notifications because the Box ID is associated with your authorised application ID when you connect to the Push Pull Notifications API.
Notification envelope
The notification body is a JSON object like this:
{
"notificationId": "1ed5f407-8096-40d1-87ef-9a2a103eeb85",
"boxId": "50dca3fc-c37c-4f03-b719-63571333624c",
"messageContentType": "application/json",
"message": "{\"key\":\"value\"}",
"status": "RECEIVED",
"createdDateTime": "2020-06-01T10:20:23.160+0000"
}
See the API documentation for Push Pull Notifications for a description of these fields.
Notification message body
The message property in the envelope contains a stringified JSON object containing details of the Control Notification.
Example: Control Notification Message Body
{
"masterReferenceNumber": "ABCDEFGHIJKLMNOPQR",
"notificationDate": "2022-05-19T00:18:33Z",
"scheduledControlDate": "2022-05-19T00:18:33Z",
"customsOfficeOfControl": {
"referenceNumber": "ABCDEFGH"
},
"representative": {
"identificationNumber": "ABCDEFGH"
},
"transportDocument": {
"documentNumber": "ABCDEFGHIJKLMNOPQRST",
"type": "ABCD"
},
"control": [
{
"examinationPlace": {
"placeOfExamination": "ABCDEFGHIJKLMNOPQRST",
"referenceNumber": "ABCD"
},
"controlSubject": {
"consignmentMasterLevel": {
"receptacle": [
{
"receptacleIdentificationNumber": "ABCDEFGHIJKLMNOPQ"
}
],
"goodsItem": [
{
"goodsItemNumber": 1,
"packaging": [
{
"shippingMarks": "ABCDEFGHIJKLMNOPQRS",
"typeOfPackages": "AB"
},
],
"transportEquipment": [
{
"containerIdentificationNumber": "ABCDEFGHIJKLMNOPQ"
}
]
}
],
"consignmentHouseLevel": [
{
"goodsItem": [
{
"goodsItemNumber": 1,
"packaging": [
{
"shippingMarks": "ABCDEFGHIJKLMNOPQRS",
"typeOfPackages": "AB"
}
],
"passiveBorderTransportMeans": [
{
"identificationNumber": "ABCDEFGHIJKLMNOPQRSTUVWXY",
"typeOfIdentification": "12",
"nationality": "GB"
}
],
"transportEquipment": [
{
"containerIdentificationNumber": "ABCDEFGHIJKLMNOPQ"
}
]
}
],
"passiveBorderTransportMeans": [
{
"identificationNumber": "ABCDEFGHIJKLMNOPQRSTUVWXY",
"typeOfIdentification": "12",
"nationality": "GB"
}
],
"transportDocumentHouseLevel": {
"documentNumber": "ABCDEFGHIJKLMNOPQRSTUVWXY",
"type": "ABCD"
},
"transportEquipment": [
{
"containerIdentificationNumber": "ABCDEFGHIJKLMNOPQ"
}
]
}
],
"packaging": [
{
"shippingMarks": "ABCDEFGHIJKLMNOPQRS",
"typeOfPackages": "AB"
}
],
"transportEquipment": [
{
"containerIdentificationNumber": "ABCDEFGHIJKLMNOPQ"
}
]
}
}
}
],
"personNotifyingThePresentation": {
"identificationNumber": "ABCDEFGHIJKLMN"
},
"declarant": {
"identificationNumber": "ABCDEFG"
},
"notifyParty": {
"identificationNumber": "ABCDEFGHIJKLMN"
},
"metadata": {
"breadcrumb": [
{
"dateTimeMS": "2022-04-25T77:24:72.328Z",
"eventType": "ABCDEFGHIJKLMNOPQRSTUVWXY"
}
],
"messageType": "ABCDEFGHIJKLMNOPQRST"
}
}
Notification message correlation and triggers
The Control Notifications are not linked to a request received from your software. Control Notifications will be sent whenever goods require intervention.
Notification message properties
For further details of the properties returned refer to the documentation for Presentation of Goods endpoint.
For further details on PPNS, please refer Push Pull Notification API.
Inspection locations
Where an inspection of goods is required, the Control Notification will include information about the inspections that must be carried out. See the schema and examples in the zip file found in the Schemas and examples section below for details.
Technical errors
If the system is unable to respond to your Presentation Notification request, you will receive a 5xx HTTP error response.
It is possible that the system may experience unexpected problems when processing a Presentation Notification request. If this happens, your software will receive a 503 response.
Schema and examples
You can download JSON schemas and examples for request and response payloads in the API.
Presentation of Goods and Control Notification schemas with examples of messages
ZIP, 4.64KB last updated 19/12/2023
The ZIP file contains JSON files. Open in your preferred file viewer.
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 the Import Control System Presentation of Goods API.
Before testing, a user would need to obtain an Economic Operators Registration and Identification (EORI) number to be used for creating a Test User, and assigning it to the personPresentingTheGoods identificationNumber field in the Presentation Notification prior to submission. This is due to the Import Control System Presentation of Goods API needing to authorise every Presentation Notification received, otherwise a 403 Forbidden error response will be returned.
During testing, your software will always receive notifications using the Push Pull Notification Service (PPNS) API as described in the Notifications section of this documentation. You should subscribe to this API in the sandbox environment to receive these notifications.
To Note: In Production, a Control Notification will only be returned when it has been determined that goods require inspection.
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.
Endpoints
View API endpointsWhy do these endpoints look different?
The endpoints for this API now use the Open API Specification (OAS).
The API has not changed. You do not need to make any updates to your application if you already use this API.