Goods Vehicle Movements 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 provides resources related to the Goods Vehicle Movement Service.
The Goods Vehicle Movement Service (GVMS):
Links declaration references together. This means the person moving goods only needs to present one reference at the frontier to prove that their goods have pre-lodged declarations
Links the movement of goods to declarations, meaning they can be automatically arrived and departed in HMRC systems in near-real-time
Notifies users via your software whether their inbound goods have been successfully cleared in HMRC systems by the time they arrive in the UK.
Using this API your users can:
- Create a new Goods Movement Record (GMR)
- Update a GMR, for example changing crossing details or adding declaration IDs
- List their active GMRs
- Get GMR details
- Delete a GMR
- Get GVMS reference data
If you are building your own user-facing service using this API, you should not redirect users to HMRC's
Get a Goods Movement Reference service hosted on GOV.UK.
GMRs created using this API should not subsequently be accessed using HMRC's Get a Goods Movement Reference service, or vice-versa. HMRC's Get a Goods Movement Reference service is only designed to work with GMRs it creates itself.
To learn more, read the Goods Vehicle Movement Service end-to-end guide
Errors
Testing
You can use the sandbox environment to test this API.
When testing, your software will be sent notifications using the Push Pull Notifications API as described in the Notifications section of this documentation. You should subscribe to this API in the sandbox environment to receive these notifications.
Use the Get reference data endpoint to get JSON containing the list of valid routeId
s and other identifiers referenced in this API. Routes whose effectiveFrom
-effectiveTo
date range falls outside the current date can be used in the sandbox environment, but not in production.
After creating a GMR, you can use the gmrId
provided in the resultant notification message with the Update GMR endpoint.
You are free to provide any schematically valid data to the endpoints in the sandbox environment.
POSTing or PUTing GMRs in the sandbox may result in ruleFailures
being returned in the notification, and a GMR status of NOT_FINALISABLE
.
The sandbox environment will not replicate all the potential ruleFailures
codes that can occur in the production service, but
will return them in certain circumstances such as:
isUnaccompanied
must be providedvehicleRegNum
must be provided whereisUnaccompanied
is set tofalse
sAndSMasterRefNum
ineidrDeclarations
must be provided wheredirection
is set toUK_INBOUND
orGB_TO_NI
The list of possible rule codes and descriptions for the production service is provided in the JSON returned by the Get reference data endpoint. This will be updated as and when validation rules are confirmed.
Schemas and examples
You can download JSON schemas and examples for request and response payloads for all endpoints in this API.
Goods Vehicle Movements API JSON schemas and examples
ZIP, 26KB
The ZIP file contains JSON files. Open in your preferred file viewer.
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.
Barcodes
When a vehicle checks-in at a GVMS port, carriers are required to capture and present to HMRC the following details:
gmrId
andvehicleRegNum
(for accompanied movements),trailerRegistrationNums
(for unaccompanied trailers), orcontainerReferenceNums
(for unaccompanied loaded containers).
Depending on the carrier’s T&C’s you may be asked to present the gmrId
in the following ways:
- Enter a
gmrId
during the carrier’s booking process - Present a GMR barcode for scanning at check-in
- Present a
gmrId
at check-in
Your software can create a GMR barcode by using the Code 128 linear barcode standard.
Many software libraries are available that can perform this function for you.
The value to encode is the gmrId
as returned by this API (uppercase with no spaces or dashes).
Notifications
Some endpoints in this API respond with 202 Accepted
and provide a notification of the outcome of the GMR operation via the
Push Pull Notifications API.
Notifications will also be created when events occur that change the status of a GMR.
These notifications can either be pushed to you via a POST to an endpoint you provide, or pulled by you via a GET endpoint that the Push Pull Notifications API provides.
When you use this API to create or update a GMR, you will receive the response headers as described in the endpoints documentation:
- Notification-Message-Id
- Notification-Box-Id
The Notification-Message-Id
gives you the ID of the message that will be sent in response to your request.
You will receive additional notifications when other things happen to your GMR, such as check-in, embarkation, or problems caused by changes to declarations in CDS or CHIEF.
The Notification-Box-Id
is specific to GVMS and your application. All your GVMS notifications will be sent to the same
Notification-Box-Id
. Other applications will not be able to access these notifications because the Box ID is associated
with your authorized 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 for the latest status of a GMR.
Example 1: Recently created GMR with rule failures
{ "messageId": "90b6abd2-f7f9-4223-97c0-29f0c10bbf8e", "gmrId": "GMRA000002FK", "gmrStatusVersion": 2, "createdDateTime": "2021-08-11T10:58:12.384Z", "updatedDateTime": "2021-08-11T10:58:12.384Z", "gmrState": "NOT_FINALISABLE", "ruleFailures": [ { "code": "007", "technicalMessage": "Safety and security MRN not found", "field": "$.customsDeclarations[3].sAndSMasterRefNum", "value": "83736521" }, { "code": "008", "technicalMessage": "Transit declaration not found", "field": "$.transitDeclarations[1].transitDeclarationId", "value": "384716253" } ] }
Example 2: Inspection required on embarked inbound movement
{ "messageId": "714d1c3a-638a-44d2-9830-80736b0936f4", "gmrId": "GMRA00002KW2", "gmrStatusVersion": 4, "createdDateTime": "2021-08-11T10:58:12.384Z", "updatedDateTime": "2021-08-12T16:39:03.198Z", "gmrState": "EMBARKED", "inspectionRequired": true, "reportToLocations": [ { "inspectionTypeId": "1", "locationIds": [ "L0029A", "L0030A", "L0031A" ] }, { "inspectionTypeId": "2", "locationIds": [ "L0029A", "L0031A" ] } ] }
Example 3: Inspection not currently required on outbound movement
{ "messageId": "c68a4442-6336-439f-8dda-5d729fff775c", "gmrId": "GMRB0000F2KW", "gmrStatusVersion": 3, "createdDateTime": "2021-09-11T10:58:12.384Z", "updatedDateTime": "2021-09-24T04:23:50.384Z", "gmrState": "CHECKED_IN", "inspectionRequired": false }
Notification message correlation and triggers
The messageId
field is a unique identifier present in every notification message
. If you call an endpoint
that returns 202 Accepted
, you will receive a Notification-Message-Id
response header which
will contain the messageId
of a subsequent notification that will be sent in response to
your request.
Not all notifications sent are linked to a request received from your software. Notifications will be sent whenever the status of a GMR changes. This includes:
- When a GMR is created or updated
- When a GMR is checked-in with a carrier
- When a vehicle with a checked-in GMR embarks on a crossing
- When HMRC need to notify you that an inspection is or is not required
- When changes to the status of declarations within a GMR result in the GMR becoming
NOT_FINALISABLE
- When a technical issue occurred that meant GVMS could not create the requested GMR
Notification message properties
All properties in the notification message body with the exception of messageId
are also included in the
Get Goods Movement Record
endpoint response body under the metadata
object.
For details of the properties returned refer to the documentation for that endpoint.
Rule failure codes
If the GMR is NOT_FINALISABLE
, the notification will include entries under ruleFailures
.
The code
property value will be one of the ruleId
s found in the ruleFailures
list within GVMS Reference Data. This list in reference data describes what each code means, for example the description for code 011_1
is “The customs declaration has been used in another goods movement reference.”
What your software or the user should do depends on the code:
- Codes starting with 9 indicate a system error. We recommend retrying the request in a few moments. If the error was in response to a Create GMR request and includes a new GMR ID, then you should either retry using Update GMR with the GMR ID provided or call Delete GMR to ensure any declarations linked to the GMR in error can be used in other GMRs. If the error continues, contact the HMRC Software Developer Support Team.
- Code
025_4
indicates that a transit MRN entered could not be found in the national database and needs to be looked up in the Office of Departure database. This international look-up may take seconds or hours. The user should check that they have entered the correct MRN. It should be from the Transit Accompanying Document (TAD) and not the Export Accompanying Document (EAD). If the user believes the MRN is correct, your software can resend the GMR. If the look-up process is complete this will result in code025_5
indicating that the MRN was not found or was found to be invalid, or in no rule failure if the MRN was found and is valid. - Other codes typically require the user to update the GMR. Your software should then call the Update GMR endpoint with the updated GMR data.
Inspection notifications for arrived exports
For export movements traveling via ports operating the arrived exports process (e.g. Dover, Eurotunnel, Holyhead), the driver may need to report for an inspection at an Inland Border Facility prior to checking-in at the departure port. Where this is required, GVMS notifications will include the inspectionRequired
flag set to true, along with the 094_1
code in the ruleFailures
list and a NOT_FINALISABLE
state.
Hauliers should ensure any other problems identified in the ruleFailures
are fixed before the vehicle is directed for the export inspection. Failure to do this will prevent the vehicle from checking-in at the departure port after the inspection is complete because there will still be outstanding issues with the GMR.
The vehicle may depart to the inspection facility when 094_1
is the only ruleFailure
code present. Once the inspection is complete and the declarations are cleared in CHIEF/CDS, GVMS will send a notification with the inspectionRequired
flag removed and no ruleFailures
. The GMR state will also change from NOT_FINALISABLE
to OPEN
indicating that the vehicle is now cleared to proceed to check-in at the port.
Inspection locations
Where an inspection is required for a GMR, the notification will include information about the inspections that must be carried out. This applies to both imports and exports. See the schema and examples in the zip file found in the Schemas and examples section below for details. See also the list of inspection locations and types in GVMS reference data JSON returned by the Get GVMS reference data endpoint.
If one or more inspections are required, the notification will include the reportToLocations
property which contains a list of one or more inspectionTypeId
s, from GVMS Reference Data, that represent the type of inspections the vehicle must have carried out, in the order specified. Not all inspection locations support all inspection types. Where there are multiple entries here, the vehicle must report for the first inspection type listed before each subsequent listed inspection. Each entry includes a list of available locations for the inspection type under the locationIds
property.
Technical errors
If the system is unable to respond to your request, you will receive a 5xx
HTTP error response.
It is possible that the system may experience unexpected problems when processing a GMR which may leave the GMR in an unknown state. If this happens, your software will receive a notification that:
- Has a ruleFailure code starting with
9
, for example901_1
- In exceptional cases may not have a
gmrId
set if the GMR ID for the message could not be established - In exceptional cases may have
gmrStatusVersion
set to-1
if ordering of notifications could not be established.
When this happens and the notification is in response to a POST
or PUT
made by your software (i.e. its messageId
matches a Notification-Message-Id
) we recommend retrying the POST
or PUT
. This should workaround any temporary system issues.
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.