This version is in beta - expect some breaking changes.

Goods Vehicle Movements 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 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

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.

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 routeIds 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 provided
  • vehicleRegNum must be provided where isUnaccompanied is set to false
  • sAndSMasterRefNum in eidrDeclarations must be provided where direction is set to UK_INBOUND or GB_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 and
  • vehicleRegNum (for accompanied movements), trailerRegistrationNums (for unaccompanied trailers), or containerReferenceNums (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 ruleIds 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 code 025_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 inspectionTypeIds, 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 example 901_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

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 endpoints
Why 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.

Is this page not working properly? (opens in new tab)