This version is in beta - expect some breaking changes.

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

Use of the GMR ID and GMR 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).

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.

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.

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.

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.

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.

Skip to main content

Endpoints

/customs/goods-movement-system/movements

List Goods Movement Records
GET

This endpoint provides a list of all the Goods Movement Records (GMRs) that you have worked on over the last 28 days.

The returned list of GMRs will contain summary information as per the example below. For the full GMR, use the Get Goods Movement Record endpoint.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:goods-movement-system scope.

Request headers

Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Authorization
required
 An OAuth 2.0 Bearer Token with the write:goods-movement-system scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

List GMRs example 

[
  {
    "gmrId": "GMRI000000F8",
    "direction": "UK_INBOUND",
    "vehicleRegNum": "AB19 DEF",
    "isUnaccompanied": false,
    "state": "NOT_FINALISABLE",
    "createdDateTime": "2020-06-11T09:48:21.592Z",
    "updatedDateTime": "2020-06-14T13:12:03.237Z",
    "plannedCrossing": {
      "routeId": "60"
    },
    "links": [
      {
        "href": "/customs/goods-movement-system/movements/GMRI000000F8",
        "method": "GET",
        "rel": "get-goods-movement-record"
      }
    ]
  },
  {
    "gmrId": "GMRB00000A9C",
    "direction": "UK_OUTBOUND",
    "vehicleRegNum": "GU51 ABC",
    "state": "OPEN",
    "plannedCrossing": {
      "routeId": "61",
      "localDateTimeOfDeparture": "2021-08-11T10:58"
    },
    "createdDateTime": "2020-06-09T09:42:15.362Z",
    "updatedDateTime": "2020-06-09T12:12:09.283Z",
    "links": [
      {
        "href": "/customs/goods-movement-system/movements/GMRB00000A9C",
        "method": "GET",
        "rel": "get-goods-movement-record"
      }
    ]
  },
  {
    "gmrId": "GMRI0000028D",
    "direction": "UK_INBOUND",
    "vehicleRegNum": "KL58 FEM",
    "state": "EMBARKED",
    "inspectionRequired": true,
    "reportToLocations": [
      {
        "inspectionTypeId": "1",
        "locationIds": [
          "L0029A", "L0030A", "L0031A"
        ]
      },
      {
        "inspectionTypeId": "2",
        "locationIds": [
          "L0029A", "L0031A"
        ]
      }
    ],
    "plannedCrossing": {
      "routeId": "60"
    },
    "checkedInCrossing": {
      "routeId": "60",
      "localDateTimeOfArrival": "2021-06-11T10:58"
    },
    "actualCrossing": {
      "routeId": "60",
      "localDateTimeOfArrival": "2021-06-11T11:03"
    },
    "createdDateTime": "2020-06-08T08:42:11.901Z",
    "updatedDateTime": "2020-06-08T15:23:55.471Z",
    "links": [
      {
        "href": "/customs/goods-movement-system/movements/GMRI0000028D",
        "method": "GET",
        "rel": "get-goods-movement-record"
      }
    ]
  }
]

Name Description
gmrId
string
required

The Goods Movement Record (GMR) ID for this GMR. Do not include when POSTing a GMR - GVMS will assign an ID.

Must conform to the regular expression ^GMR[A-Z][0-9A-Z]{8}$

direction
string
required

The direction of the movement - into or out of the UK, or between Great Britain and Northern Ireland

Limited to the following possible values:

UK_INBOUND - The movement is travelling into the UK
UK_OUTBOUND - The movement is travelling out of the UK
GB_TO_NI - The movement is travelling out of Great Britain into Northern Ireland
NI_TO_GB - The movement is travelling out of Northern Ireland into Great Britain
isUnaccompanied
boolean
optional

Set to true if the vehicle will not be accompanying the trailer(s) during the crossing, or if the vehicle is carrying a container that will be detached and loaded for the crossing.
inspectionRequired
boolean
optional

If set to true, indicates that the vehicle requires a customs inspection. If set to false, indicates that the vehicle does not require a customs inspection. If not set, indicates the customs inspection decision has not yet been made or is not applicable. For outbound GMRs, this indicates that the vehicle must present at an inspection facility prior to checking-in at the port. For Office of Transit inspections for inbound GMRs, a decision may be made to inspect subsequent to a notification that inspection is not required. In this event a notification will be sent that changes inspectionRequired from false to true. If this happens after leaving the port of arrival, the inspection should be carried out at the next transit office e.g. the office of destination.
reportToLocations
array
optional

Information about an inspection that is required
inspectionTypeId
string
required

An inspectionTypeId from GVMS Reference Data denoting the type of inspection that needs to be performed on the vehicle.

Must conform to the regular expression ^[0-9A-Za-z\-_]{1,100}$

locationIds
array
required

A list of locationIds from GVMS Reference Data that are available to perform this type of inspection.

Must conform to the regular expression ^[0-9A-Za-z\-_]{1,100}$

vehicleRegNum
string
optional

Vehicle registration number of the vehicle that will arrive at port. If isUnaccompanied is set to false then vehicleRegNum must be provided to check-in.

Must conform to the regular expression ^[A-Z0-9-](?:[A-Z0-9 -]{1,30})?$

trailerRegistrationNums
array
optional

For vehicles carrying trailers, the trailer registration number of each trailer. If isUnaccompanied is set to true then trailerRegistrationNums or containerReferenceNums must be provided before check-in.

Must conform to the regular expression ^[A-Z0-9-](?:[A-Z0-9 -]{1,199})?$

containerReferenceNums
array
optional

For vehicles arriving with containers that will be detached and loaded, the container reference number of each container in the movement. If isUnaccompanied is set to true then trailerRegistrationNums or containerReferenceNums must be provided before check-in.

Must conform to the regular expression ^[A-Z0-9-](?:[A-Z0-9 -]{1,199})?$

state
string
required

The state of the GMR

Limited to the following possible values:

NOT_FINALISABLE - The GMR is in a non-finalisable state. This means an update will be required from the haulier prior to check-in.
OPEN - The GMR is open for updates and is ready for check-in.
FINALISED - The GMR is finalised, which is part of the process of check-in by the carrier. No further updates from the haulier are permitted.
CHECKED_IN - The GMR is checked-in, awaiting embarkation confirmation from the carrier.
EMBARKED - The GMR is embarked, meaning the goods movement has embarked on its crossing but the goods are awaiting clearance to proceed.
COMPLETED - The GMR is completed, meaning the goods movement has embarked on its crossing and the goods are clear to proceed.
createdDateTime
string
required

The date and time that this GMR was created.

Must conform to the regular expression ^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d.\d{3}Z$

updatedDateTime
string
required

The date and time that this GMR was last updated.

Must conform to the regular expression ^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d.\d{3}Z$

plannedCrossing
object
optional

Details of the planned crossing.
routeId
string
required

The ID of the crossing route, using a routeId from the GVMS reference data

Must conform to the regular expression ^[A-Z0-9-]{1,200}$

localDateTimeOfDeparture
string
optional

The planned date and time of departure, in local time of the departure port. Must not include seconds, time zone or UTC marker

Must conform to the regular expression ^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d$

checkedInCrossing
object
optional

Details of the crossing that the vehicle has been checked-in to. These details will only be present in the Goods Movement Record after the vehicle has checked in.
routeId
string
required

The ID of the crossing route, using a routeId from the GVMS reference data

Must conform to the regular expression ^[A-Z0-9-]{1,200}$

localDateTimeOfArrival
string
required

The planned date and time of arrival, in local time of the arrival port. Must not include seconds, time zone or UTC marker

Must conform to the regular expression ^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d$

actualCrossing
object
optional

Details of the crossing that the goods movement has been embarked on. These details will only be present in the Goods Movement Record after the vehicle has embarked on a crossing.
routeId
string
required

The ID of the crossing route, using a routeId from the GVMS reference data

Must conform to the regular expression ^[A-Z0-9-]{1,200}$

localDateTimeOfArrival
string
required

The planned date and time of arrival, in local time of the arrival port. Must not include seconds, time zone or UTC marker

Must conform to the regular expression ^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d$

links
array
optional

An endpoint link that indicates a possible action related to the current resource
href
string
required

The relative URL of the endpoint
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

GET
rel
string
required

A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource.

Limited to the following possible values:

get-goods-movement-record

Error scenarios

Scenario HTTP status Code

Invalid JSON - the payload could not be parsed

400 (Bad Request)

INVALID_JSON_FORMAT

The JSON payload is not conformant with the JSON schema

400 (Bad Request)

JSON_SCHEMA_ERROR

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section
/customs/goods-movement-system/movements

Create Goods Movement Record
POST

This endpoint is used to create a Goods Movement Record (GMR)

When creating, you can provide the full record or you can provide incomplete information and update it later using the Update GMR endpoint.

Finalisation will not be possible until the record is complete.

If the GMR you POST is schematically invalid, you will receive details of the schematic errors in a 400 error response.

If the GMR you POST is schematically valid, the endpoint will respond with a 202 Accepted and you will receive a notification after a few seconds detailing the status of the GMR. This notification will confirm if the GMR is "finalisable", i.e. ready to be finalised or "not finalisable", i.e. an update to the GMR is required.

If it is "not finalisable" then the parts of the GMR that are invalid or missing will be identified in the notification.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:goods-movement-system scope.

Request headers

Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Content-Type
required

Specifies the format of the request body, which must be JSON.

For example: application/json
Authorization
required
 An OAuth 2.0 Bearer Token with the write:goods-movement-system scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Standard movement GMR example 

{
  "direction": "GB_TO_NI",
  "isUnaccompanied": false,
  "vehicleRegNum": "AB19 DEF",
  "plannedCrossing": {
    "routeId": "178",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "customsDeclarations": [
    {
      "customsDeclarationId": "0GB689223596000-SE119404",
      "sAndSMasterRefNum": "20GB01I0XLM976S001"
    }, {
      "customsDeclarationId": "0GB689223596000-SE119405",
      "sAndSMasterRefNum": "20GB01I0XLM976S002"
    }, {
      "customsDeclarationId": "0GB689223596000-SE119406",
      "customsDeclarationPartId": "34J",
      "sAndSMasterRefNum": "20GB01I0XLM976S003"
    }
  ],
  "transitDeclarations": [
    {
      "transitDeclarationId": "10GB00002910B75BE5",
      "isTSAD": true
    }, {
      "transitDeclarationId": "10GB00002910B75BE6",
      "sAndSMasterRefNum": "20GB01I0XLM976S004",
      "isTSAD": false
    }
  ]
}

Scenario: EIDR movement GMR example 

{
  "direction": "GB_TO_NI",
  "isUnaccompanied": false,
  "vehicleRegNum": "AB19 DEF",
  "trailerRegistrationNums": ["KF293716", "GH28372S"],
  "plannedCrossing": {
    "routeId": "178",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "eidrDeclarations": [
    {
      "traderEORI": "GB123456789012",
      "sAndSMasterRefNum": "20GB01I0XLM976S003"
    }
  ]
}

Scenario: Empty movement GMR example 

{
  "direction": "UK_OUTBOUND",
  "isUnaccompanied": false,
  "vehicleRegNum": "AB19 DEF",
  "plannedCrossing": {
    "routeId": "61",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "emptyVehicle": {
    "isOwnVehicle": true,
    "sAndSMasterRefNum": "20GB01I0XLM976S003"
  }
}

Scenario: Unaccompanied ATA carnet container movement GMR example 

{
  "direction": "UK_OUTBOUND",
  "isUnaccompanied": true,
  "containerReferenceNums": ["CSQU3054383"],
  "plannedCrossing": {
    "routeId": "61",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "ataDeclarations": [
    {
      "ataCarnetId": "SDOEFOK2982893"
    }
  ]
}

Scenario: TIR movement GMR example 

{
  "direction": "GB_TO_NI",
  "isUnaccompanied": true,
  "trailerRegistrationNums": ["KF293716", "GH28372S"],
  "plannedCrossing": {
    "routeId": "178",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "sAndSMasterRefNum": "20GB01I0XLM976S001",
  "tirDeclarations": [
    {
      "tirCarnetId": "FEOKEOK092927"
    }
  ]
}

Scenario: Indirect Export Declarations movement GMR example 

{
  "direction": "NI_TO_GB",
  "isUnaccompanied": false,
  "vehicleRegNum": "AB19 DEF",
  "plannedCrossing": {
    "routeId": "179",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "indirectExportDeclarations": [
    {
      "eadMasterRefNum": "20IE01I0XLM976S003"
    },
    {
      "eadMasterRefNum": "20IE01I0XLM976S004"
    }
  ]
}

Scenario: Oral or By Conduct Declaration example 

{
  "direction": "UK_OUTBOUND",
  "isUnaccompanied": false,
  "vehicleRegNum": "AB19 DEF",
  "trailerRegistrationNums": ["KF293716", "GH28372S"],
  "plannedCrossing": {
    "routeId": "61",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "dbcDeclaration": {
    "isOwnVehicle": false,
    "dbcGoods": [
      {
        "sAndSMasterRefNum": "GB12323020392"
      },
      {
        "sAndSMasterRefNum": "GB12323020393"
      }
    ]
  }
}

Scenario: SAD Declaration example 

{
  "direction": "UK_INBOUND",
  "isUnaccompanied": false,
  "vehicleRegNum": "AB19 DEF",
  "plannedCrossing": {
    "routeId": "61",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "sadDeclaration": {
    "sadGoods": [
      {
        "sAndSMasterRefNum": "GB12323020392"
      },
      {
        "sAndSMasterRefNum": "GB12323020393"
      }
    ]
  }
}

Name Description
direction
string
required

The direction of the movement - into or out of the UK, or between Great Britain and Northern Ireland

Limited to the following possible values:

UK_INBOUND - The movement is travelling into the UK
UK_OUTBOUND - The movement is travelling out of the UK
GB_TO_NI - The movement is travelling out of Great Britain into Northern Ireland
NI_TO_GB - The movement is travelling out of Northern Ireland into Great Britain
haulierType
string
optional

The type of haulier moving the goods

Limited to the following possible values:

STANDARD - All hauliers that are not one of the other types
FPO_ASN - Fast parcel operators that are members of the Anti-Smuggling Network
FPO_OTHER - Fast parcel operators that are not members of the ASN and are not moving goods with a Memorandum of Understanding
NATO_MOD - NATO or MoD
RMG - Royal Mail Group
ETOE - Extra-Territorial Office of Exchange
isUnaccompanied
boolean
optional

Set to true if the vehicle will not be accompanying the trailer(s) during the crossing, or if the vehicle is carrying a container that will be detached and loaded for the crossing.
vehicleRegNum
string
optional

Vehicle registration number of the vehicle that will arrive at port. If isUnaccompanied is set to false then vehicleRegNum must be provided to check-in.

Must conform to the regular expression ^[A-Z0-9-](?:[A-Z0-9 -]{1,30})?$

trailerRegistrationNums
array
optional

For vehicles carrying trailers, the trailer registration number of each trailer. If isUnaccompanied is set to true then trailerRegistrationNums or containerReferenceNums must be provided before check-in.

Must conform to the regular expression ^[A-Z0-9-](?:[A-Z0-9 -]{1,199})?$

containerReferenceNums
array
optional

For vehicles arriving with containers that will be detached and loaded, the container reference number of each container in the movement. If isUnaccompanied is set to true then trailerRegistrationNums or containerReferenceNums must be provided before check-in.

Must conform to the regular expression ^[A-Z0-9-](?:[A-Z0-9 -]{1,199})?$

plannedCrossing
object
optional

Details of the planned crossing.
routeId
string
required

The ID of the crossing route, using a routeId from the GVMS reference data

Must conform to the regular expression ^[A-Z0-9-]{1,200}$

localDateTimeOfDeparture
string
optional

The planned date and time of departure, in local time of the departure port. Must not include seconds, time zone or UTC marker

Must conform to the regular expression ^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d$

sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers the whole trailer and not individual consignments. This applies to both ENS and EXS declarations.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

customsDeclarations
array
optional

Details of the customs declarations within this goods load.
customsDeclarationId
string
required

This is the identifier for a customs declaration from Customs Declaration Service (CDS) or CHIEF. For inbound movements declared in CDS it is a MRN, for example 19GB4S24GC3PPFGVR7. For inbound movements declared in CHIEF it is an ERN, for example 999123456C20210615. For outbound movements declared in either CDS or CHIEF it is a DUCR, for example 0GB689223596000-SE119404.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

customsDeclarationPartId
string
optional

Supported in Production environment after 5 September 2021. If a DUCR from CHIEF has been added in customsDeclarationId, this is the optional part ID. Must match the part ID for the declaration entered in CHIEF including any leading zeroes.

Must conform to the regular expression ^[0-9]{1,3}[A-Z]?$

sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers individual consignments within a trailer. This applies to both ENS and EXS declarations. If there is one, include the S&S MRN for the customs declaration above here.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

sadDeclaration
object
optional

Details of a stamped, paper-based declaration using a Single Administrative Document (SAD). Only intended for use when technical issues prevent use of Transit IT systems.
sadGoods
array
optional

References for goods loads moving under a stamped paper SAD.
sAndSMasterRefNum
string
required

The master reference number (MRN) for a Safety & Security declaration, where applicable.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

transitDeclarations
array
optional

Details of the transit declarations within this goods load.
transitDeclarationId
string
required

This is the Transit MRN issued by the Office of Departure. Must be provided.

Must conform to the regular expression ^\d{2}[A-Z]{2}[A-Z0-9]{14}$

isTSAD
boolean
required

Set to true if the transit declaration is a TSAD, otherwise set to false (for a TAD)
sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers individual Transit consignments within a trailer. This applies to both ENS and EXS declarations. If there is one, include the S&S MRN for the Transit declaration above here.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

tirDeclarations
array
optional

Details of one or more TIR Carnet declarations. Must be provided prior to check-in for TIR movements.
tirCarnetId
string
required

The TIR Carnet ID for the carnet within a TIR goods movement

Must conform to the regular expression ^.{1,200}$

sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers TIR Carnet consignments within a trailer. This applies to both ENS and EXS declarations. If there is one, include the S&S MRN for the TIR declaration above here.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

ataDeclarations
array
optional

Details of one or more ATA Carnet declarations. Must be provided prior to check-in for ATA movements.
ataCarnetId
string
required

The ATA Carnet ID for the carnet within an ATA goods movement

Must conform to the regular expression ^.{1,200}$

sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers ATA Carnet consignments within a trailer. This applies to both ENS and EXS declarations. If there is one, include the S&S MRN for the TIR declaration above here.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

eidrDeclarations
array
optional

Details of one or more EIDR declarations. Must be provided prior to check-in for EIDR movements. For movements using a specially-issued EORI, the same EORI may be entered multiple times, one entry for each ENS S&S MRN travelling under EIDR.
traderEORI
string
required

The trader's EORI

Must conform to the regular expression ^[A-Z]{2}[0-9]{12,15}$

sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers individual EIDR consignments within a trailer. This applies to both ENS and EXS declarations. If there is one, include the S&S MRN for the EIDR declaration above here.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

indirectExportDeclarations
array
optional

Details of the indirect export declarations within this goods load. Only valid for NI to GB movements where the goods originated from outside UK.
eadMasterRefNum
string
required

The master or movement reference number (MRN) of the Export Accompanying Document (EAD) for this indirect export.

Must conform to the regular expression ^\d{2}[A-Z]{2}[A-Z0-9]{14}$

emptyVehicle
object
optional

Declares that this is an empty movement and contains details about the empty movement. Must be provided prior to check-in for empty movements.
isOwnVehicle
boolean
required

Set to false if the haulier is moving the goods vehicle under a contract of carriage. Set to true if there is no contract of carriage.
sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers a trailer that is moving under a contract of carriage. This applies to both ENS and EXS declarations.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

dbcDeclaration
object
optional

Declares goods moving under Declaration by Conduct. Refer to the Oral and By Conduct List published at gov.uk for details.
isOwnVehicle
boolean
required

Set to false if the haulier is moving the goods vehicle under a contract of carriage. Set to true if there is no contract of carriage.
dbcGoods
array
optional

References for a Declaration by Conduct goods load.
sAndSMasterRefNum
string
required

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This may be required when the S&S declaration covers a DBC that is moving under a contract of carriage. This applies to both ENS and EXS declarations.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

exemptionDeclaration
object
optional

Declares Royal Mail Group or ETOE goods in the movement that do not require a customs declaration.
exemptedGoods
array
optional

The list of goods loads exempted from customs. Used for GB>NI RMG <£900 B2B or GB>EU FPO+MOU goods loads.
sAndSMasterRefNum
string
required

The MRN or DUCR (depending on direction) for an ENS or EXS Safety & Security declaration for this goods load.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

Responses

HTTP status 202 (Accepted)

Response headers

Name Description
Notification-Message-Id
required

The messageId that will be included in a notification message created in response to this request. See above for more information about notifications.

For example: 368ed1fc-a082-41cb-a8bd-ac04cc5bdc55
Notification-Box-Id
required

The boxId to use when retrieving the notification created in response to this request. See above for more information about notifications.

For example: 3af01911-75ed-4412-a12d-ca80f626ab10

See also fraud prevention.

Error scenarios

Scenario HTTP status Code

Invalid JSON - the payload could not be parsed

400 (Bad Request)

INVALID_JSON_FORMAT

The JSON payload is not conformant with the JSON schema

400 (Bad Request)

JSON_SCHEMA_ERROR

The GMR is for a movement direction that is not yet active under current customs controls

400 (Bad Request)

NOT_YET_SUPPORTED

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section
/customs/goods-movement-system/movements/{gmrId}

Get Goods Movement Record
GET

This endpoint gets a Goods Movement Record (GMR)

The returned GMR will reflect the latest record received with the given GMR ID, and will include a metadata object detailing the GMR's current status and any errors or issues.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:goods-movement-system scope.

Path parameters

Name Description
gmrId
string
required

The ID of a Goods Movement Record (GMR)

For example: 2234567890

Request headers

Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Authorization
required
 An OAuth 2.0 Bearer Token with the write:goods-movement-system scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 200 (OK)

Example of GMR with errors (non-finalisable) 

{
  "gmrId": "GMRB000000F8",
  "haulierEORI": "GB123456789012",
  "metadata": {
    "state": "NOT_FINALISABLE",
    "gmrStatusVersion": 2,
    "createdDateTime": "2021-08-11T10:58:12.384Z",
    "updatedDateTime": "2021-08-12T16:39:03.198Z",
    "ruleFailures": [
      {
        "code": "007",
        "technicalMessage": "Safety and security MRN not found",
        "field": "$.customsDeclarations[3].sAndSMasterRefNum",
        "value": "20GB01I0XLM976S003"
      },
      {
        "code": "008",
        "technicalMessage": "Transit declaration not found",
        "field": "$.transitDeclarations[1].transitDeclarationId",
        "value": "10GB00002910B75BE6"
      }
    ]
  },
  "direction": "UK_OUTBOUND",
  "isUnaccompanied": false,
  "vehicleRegNum": "AB19 DEF",
  "trailerRegistrationNums": ["KF293716", "GH28372S"],
  "plannedCrossing": {
    "routeId": "61",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "customsDeclarations": [
    {
      "customsDeclarationId": "0GB689223596000-SE119404",
      "sAndSMasterRefNum": "20GB01I0XLM976S001"
    }, {
      "customsDeclarationId": "0GB689223596000-SE119405",
      "sAndSMasterRefNum": "20GB01I0XLM976S002"
    }, {
      "customsDeclarationId": "0GB689223596000-SE119406",
      "sAndSMasterRefNum": "20GB01I0XLM976S003"
    }
  ],
  "transitDeclarations": [
      {
        "transitDeclarationId": "10GB00002910B75BE5",
        "isTSAD": true
      }, {
        "transitDeclarationId": "10GB00002910B75BE6",
        "sAndSMasterRefNum": "20GB01I0XLM976S004",
        "isTSAD": false
      }
  ],
  "links": [
    {
      "href": "/customs/goods-movement-system/movements/GMRB000000F8",
      "method": "PUT",
      "rel": "update-goods-movement-record"
    },
    {
      "href": "/customs/goods-movement-system/movements/GMRA000000F8",
      "method": "DELETE",
      "rel": "delete-goods-movement-record"
    }
  ]
}

Example of embarked GMR marked with "inspectionRequired" 

{
  "gmrId": "GMRI00000RM2",
  "haulierEORI": "GB123456789012",
  "metadata": {
    "state": "EMBARKED",
    "gmrStatusVersion": 6,
    "reportToLocations": [
      {
        "inspectionTypeId": "1",
        "locationIds": [
          "L0029A", "L0030A", "L0031A"
        ]
      },
      {
        "inspectionTypeId": "2",
        "locationIds": [
          "L0029A", "L0031A"
        ]
      }
    ],
    "inspectionRequired": true,
    "createdDateTime": "2021-08-11T10:58:12.384Z",
    "updatedDateTime": "2021-08-12T16:39:03.198Z"
  },
  "direction": "UK_INBOUND",
  "isUnaccompanied": false,
  "vehicleRegNum": "AB19 DEF",
  "trailerRegistrationNums": ["KF293716", "GH28372S"],
  "plannedCrossing": {
    "routeId": "60",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "eidrDeclarations": [
    {
      "traderEORI": "GB123456789012",
      "sAndSMasterRefNum": "20FR01I0XLM976S003"
    }
  ]
}

Example of Indirect Export Declarations 

{
  "gmrId": "GMRI00000RM2",
  "haulierEORI": "GB123456789012",
  "metadata": {
    "state": "EMBARKED",
    "gmrStatusVersion": 6,
    "inspectionRequired": true,
    "createdDateTime": "2021-08-11T10:58:12.384Z",
    "updatedDateTime": "2021-08-12T16:39:03.198Z"
  },
  "direction": "NI_TO_GB",
  "isUnaccompanied": false,
  "vehicleRegNum": "AB19 DEF",
  "trailerRegistrationNums": ["KF293716", "GH28372S"],
  "plannedCrossing": {
    "routeId": "179",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "indirectExportDeclarations": [
    {
      "eadMasterRefNum": "20IE01I0XLM976S003"
    },
    {
      "eadMasterRefNum": "20IE01I0XLM976S004"
    }
  ]
}

Name Description
gmrId
string
required

The Goods Movement Record (GMR) ID for this GMR. Do not include when POSTing a GMR - GVMS will assign an ID.

Must conform to the regular expression ^GMR[A-Z][0-9A-Z]{8}$

haulierEORI
string
required

The EORI of the haulier that is responsible for the vehicle making the goods movement

Must conform to the regular expression ^GB[0-9]{12,15}$

metadata
object
required

Information from the Goods Vehicle Movement Service about this GMR.
state
string
required

The state of the GMR

Limited to the following possible values:

NOT_FINALISABLE - The GMR is in a non-finalisable state. This means an update will be required from the haulier prior to check-in.
OPEN - The GMR is open for updates and is ready for check-in.
FINALISED - The GMR is finalised, which is part of the process of check-in by the carrier. No further updates from the haulier are permitted.
CHECKED_IN - The GMR is checked-in, awaiting embarkation confirmation from the carrier.
EMBARKED - The GMR is embarked, meaning the goods movement has embarked on its crossing but the goods are awaiting clearance to proceed.
COMPLETED - The GMR is completed, meaning the goods movement has embarked on its crossing and the goods are clear to proceed.
gmrStatusVersion
integer
required

The version number of the latest status notification for this GMR. Each new notification for a given GMR will have a greater gmrStatusVersion than the last.
inspectionRequired
boolean
optional

If set to true, indicates that the vehicle requires a customs inspection. If set to false, indicates that the vehicle does not require a customs inspection. If not set, indicates the customs inspection decision has not yet been made or is not applicable. For outbound GMRs, this indicates that the vehicle must present at an inspection facility prior to checking-in at the port. For Office of Transit inspections for inbound GMRs, a decision may be made to inspect subsequent to a notification that inspection is not required. In this event a notification will be sent that changes inspectionRequired from false to true. If this happens after leaving the port of arrival, the inspection should be carried out at the next transit office e.g. the office of destination.
reportToLocations
array
optional

Information about an inspection that is required
inspectionTypeId
string
required

An inspectionTypeId from GVMS Reference Data denoting the type of inspection that needs to be performed on the vehicle.

Must conform to the regular expression ^[0-9A-Za-z\-_]{1,100}$

locationIds
array
required

A list of locationIds from GVMS Reference Data that are available to perform this type of inspection.

Must conform to the regular expression ^[0-9A-Za-z\-_]{1,100}$

createdDateTime
string
required

The date and time that this GMR was created.

Must conform to the regular expression ^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d.\d{3}Z$

updatedDateTime
string
required

The date and time that this GMR was last updated.

Must conform to the regular expression ^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d.\d{3}Z$

ruleFailures
array
optional

If the GMR is not finalisable, the reasons why are listed here. These must be rectified in subsequent calls to the PUT API prior to check-in.
code
string
required

A code indicating the ID of the rule that failed
technicalMessage
string
required

A message describing the rule that failed
field
string
optional

A JSONPath pointing to the field that this rule failure concerns. Only included if the rule concerns a specific field e.g. a specific MRN.
value
string
optional

The value of the JSON field that this rule failure concerns. Only included if the rule concerns a specific field e.g. a specific MRN.
direction
string
required

The direction of the movement - into or out of the UK, or between Great Britain and Northern Ireland

Limited to the following possible values:

UK_INBOUND - The movement is travelling into the UK
UK_OUTBOUND - The movement is travelling out of the UK
GB_TO_NI - The movement is travelling out of Great Britain into Northern Ireland
NI_TO_GB - The movement is travelling out of Northern Ireland into Great Britain
haulierType
string
optional

The type of haulier moving the goods

Limited to the following possible values:

STANDARD - All hauliers that are not one of the other types
FPO_ASN - Fast parcel operators that are members of the Anti-Smuggling Network
FPO_OTHER - Fast parcel operators that are not members of the ASN and are not moving goods with a Memorandum of Understanding
NATO_MOD - NATO or MoD
RMG - Royal Mail Group
ETOE - Extra-Territorial Office of Exchange
isUnaccompanied
boolean
optional

Set to true if the vehicle will not be accompanying the trailer(s) during the crossing, or if the vehicle is carrying a container that will be detached and loaded for the crossing.
vehicleRegNum
string
optional

Vehicle registration number of the vehicle that will arrive at port. If isUnaccompanied is set to false then vehicleRegNum must be provided to check-in.

Must conform to the regular expression ^[A-Z0-9-](?:[A-Z0-9 -]{1,30})?$

trailerRegistrationNums
array
optional

For vehicles carrying trailers, the trailer registration number of each trailer. If isUnaccompanied is set to true then trailerRegistrationNums or containerReferenceNums must be provided before check-in.

Must conform to the regular expression ^[A-Z0-9-](?:[A-Z0-9 -]{1,199})?$

containerReferenceNums
array
optional

For vehicles arriving with containers that will be detached and loaded, the container reference number of each container in the movement. If isUnaccompanied is set to true then trailerRegistrationNums or containerReferenceNums must be provided before check-in.

Must conform to the regular expression ^[A-Z0-9-](?:[A-Z0-9 -]{1,199})?$

plannedCrossing
object
optional

Details of the planned crossing.
routeId
string
required

The ID of the crossing route, using a routeId from the GVMS reference data

Must conform to the regular expression ^[A-Z0-9-]{1,200}$

localDateTimeOfDeparture
string
optional

The planned date and time of departure, in local time of the departure port. Must not include seconds, time zone or UTC marker

Must conform to the regular expression ^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d$

checkedInCrossing
object
optional

Details of the crossing that the vehicle has been checked-in to. These details will only be present in the Goods Movement Record after the vehicle has checked in.
routeId
string
required

The ID of the crossing route, using a routeId from the GVMS reference data

Must conform to the regular expression ^[A-Z0-9-]{1,200}$

localDateTimeOfArrival
string
required

The planned date and time of arrival, in local time of the arrival port. Must not include seconds, time zone or UTC marker

Must conform to the regular expression ^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d$

actualCrossing
object
optional

Details of the crossing that the goods movement has been embarked on. These details will only be present in the Goods Movement Record after the vehicle has embarked on a crossing.
routeId
string
required

The ID of the crossing route, using a routeId from the GVMS reference data

Must conform to the regular expression ^[A-Z0-9-]{1,200}$

localDateTimeOfArrival
string
required

The planned date and time of arrival, in local time of the arrival port. Must not include seconds, time zone or UTC marker

Must conform to the regular expression ^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d$

sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers the whole trailer and not individual consignments. This applies to both ENS and EXS declarations.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

customsDeclarations
array
optional

Details of the customs declarations within this goods load.
customsDeclarationId
string
required

This is the identifier for a customs declaration from Customs Declaration Service (CDS) or CHIEF. For inbound movements declared in CDS it is a MRN, for example 19GB4S24GC3PPFGVR7. For inbound movements declared in CHIEF it is an ERN, for example 999123456C20210615. For outbound movements declared in either CDS or CHIEF it is a DUCR, for example 0GB689223596000-SE119404.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

customsDeclarationPartId
string
optional

Supported in Production environment after 5 September 2021. If a DUCR from CHIEF has been added in customsDeclarationId, this is the optional part ID. Must match the part ID for the declaration entered in CHIEF including any leading zeroes.

Must conform to the regular expression ^[0-9]{1,3}[A-Z]?$

sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers individual consignments within a trailer. This applies to both ENS and EXS declarations. If there is one, include the S&S MRN for the customs declaration above here.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

sadDeclaration
object
optional

Details of a stamped, paper-based declaration using a Single Administrative Document (SAD). Only intended for use when technical issues prevent use of Transit IT systems.
sadGoods
array
optional

References for goods loads moving under a stamped paper SAD.
sAndSMasterRefNum
string
required

The master reference number (MRN) for a Safety & Security declaration, where applicable.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

transitDeclarations
array
optional

Details of the transit declarations within this goods load.
transitDeclarationId
string
required

This is the Transit MRN issued by the Office of Departure. Must be provided.

Must conform to the regular expression ^\d{2}[A-Z]{2}[A-Z0-9]{14}$

isTSAD
boolean
required

Set to true if the transit declaration is a TSAD, otherwise set to false (for a TAD)
sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers individual Transit consignments within a trailer. This applies to both ENS and EXS declarations. If there is one, include the S&S MRN for the Transit declaration above here.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

tirDeclarations
array
optional

Details of one or more TIR Carnet declarations. Must be provided prior to check-in for TIR movements.
tirCarnetId
string
required

The TIR Carnet ID for the carnet within a TIR goods movement

Must conform to the regular expression ^.{1,200}$

sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers TIR Carnet consignments within a trailer. This applies to both ENS and EXS declarations. If there is one, include the S&S MRN for the TIR declaration above here.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

ataDeclarations
array
optional

Details of one or more ATA Carnet declarations. Must be provided prior to check-in for ATA movements.
ataCarnetId
string
required

The ATA Carnet ID for the carnet within an ATA goods movement

Must conform to the regular expression ^.{1,200}$

sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers ATA Carnet consignments within a trailer. This applies to both ENS and EXS declarations. If there is one, include the S&S MRN for the TIR declaration above here.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

eidrDeclarations
array
optional

Details of one or more EIDR declarations. Must be provided prior to check-in for EIDR movements. For movements using a specially-issued EORI, the same EORI may be entered multiple times, one entry for each ENS S&S MRN travelling under EIDR.
traderEORI
string
required

The trader's EORI

Must conform to the regular expression ^[A-Z]{2}[0-9]{12,15}$

sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers individual EIDR consignments within a trailer. This applies to both ENS and EXS declarations. If there is one, include the S&S MRN for the EIDR declaration above here.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

indirectExportDeclarations
array
optional

Details of the indirect export declarations within this goods load. Only valid for NI to GB movements where the goods originated from outside UK.
eadMasterRefNum
string
required

The master or movement reference number (MRN) of the Export Accompanying Document (EAD) for this indirect export.

Must conform to the regular expression ^\d{2}[A-Z]{2}[A-Z0-9]{14}$

emptyVehicle
object
optional

Declares that this is an empty movement and contains details about the empty movement. Must be provided prior to check-in for empty movements.
isOwnVehicle
boolean
required

Set to false if the haulier is moving the goods vehicle under a contract of carriage. Set to true if there is no contract of carriage.
sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers a trailer that is moving under a contract of carriage. This applies to both ENS and EXS declarations.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

dbcDeclaration
object
optional

Declares goods moving under Declaration by Conduct. Refer to the Oral and By Conduct List published at gov.uk for details.
isOwnVehicle
boolean
required

Set to false if the haulier is moving the goods vehicle under a contract of carriage. Set to true if there is no contract of carriage.
dbcGoods
array
optional

References for a Declaration by Conduct goods load.
sAndSMasterRefNum
string
required

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This may be required when the S&S declaration covers a DBC that is moving under a contract of carriage. This applies to both ENS and EXS declarations.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

exemptionDeclaration
object
optional

Declares Royal Mail Group or ETOE goods in the movement that do not require a customs declaration.
exemptedGoods
array
optional

The list of goods loads exempted from customs. Used for GB>NI RMG <£900 B2B or GB>EU FPO+MOU goods loads.
sAndSMasterRefNum
string
required

The MRN or DUCR (depending on direction) for an ENS or EXS Safety & Security declaration for this goods load.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

links
array
optional

An endpoint link that indicates a possible action related to the current resource
href
string
required

The relative URL of the endpoint
method
string
required

The HTTP method type for the endpoint

Limited to the following possible values:

GET
rel
string
required

A label for the endpoint, which describes how it is related to the current resource. The rel will be self where the action is retrieval of the same resource.

Limited to the following possible values:

update-goods-movement-record

Error scenarios

Scenario HTTP status Code

Invalid JSON - the payload could not be parsed

400 (Bad Request)

INVALID_JSON_FORMAT

The JSON payload is not conformant with the JSON schema

400 (Bad Request)

JSON_SCHEMA_ERROR

The user is not authorized to access the given GMR

403 (Forbidden)

No GMR could not be found with the provided GMR ID

404 (Not Found)

GMR_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section
/customs/goods-movement-system/movements/{gmrId}

Update Goods Movement Record
PUT

This endpoint updates a Goods Movement Record (GMR)

When updating, you can provide the full record or you can provide incomplete information and update it again later.

If the GMR you POST is schematically invalid, you will receive details of the schematic errors in a 400 error response.

If the GMR you POST is schematically valid, the endpoint will respond with a 202 Accepted and you will receive a notification after a few seconds detailing the status of the GMR. This notification will confirm if the GMR is "open", i.e. ready to be finalised or "not finalisable". In either case, updates with the PUT API can be made.

If it is "not finalisable" then the parts of the GMR that are invalid or missing will be identified in the notification.

The direction of a GMR cannot be updated. If the direction is incorrect the GMR must be deleted and a new one created.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:goods-movement-system scope.

Path parameters

Name Description
gmrId
string
required

The ID of a Goods Movement Record (GMR)

For example: 2234567890

Request headers

Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Content-Type
required

Specifies the format of the request body, which must be JSON.

For example: application/json
Authorization
required
 An OAuth 2.0 Bearer Token with the write:goods-movement-system scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Request

Scenario: Standard movement GMR example 

{
  "direction": "GB_TO_NI",
  "isUnaccompanied": false,
  "vehicleRegNum": "AB19 DEF",
  "plannedCrossing": {
    "routeId": "178",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "customsDeclarations": [
    {
      "customsDeclarationId": "0GB689223596000-SE119404",
      "sAndSMasterRefNum": "20GB01I0XLM976S001"
    }, {
      "customsDeclarationId": "0GB689223596000-SE119405",
      "sAndSMasterRefNum": "20GB01I0XLM976S002"
    }, {
      "customsDeclarationId": "0GB689223596000-SE119406",
      "customsDeclarationPartId": "34J",
      "sAndSMasterRefNum": "20GB01I0XLM976S003"
    }
  ],
  "transitDeclarations": [
    {
      "transitDeclarationId": "10GB00002910B75BE5",
      "isTSAD": true
    }, {
      "transitDeclarationId": "10GB00002910B75BE6",
      "sAndSMasterRefNum": "20GB01I0XLM976S004",
      "isTSAD": false
    }
  ]
}

Scenario: Standard movement GMR example 

{
  "direction": "UK_OUTBOUND",
  "isUnaccompanied": false,
  "vehicleRegNum": "AB19 DEF",
  "plannedCrossing": {
    "routeId": "61",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "transitDeclarations": [
    {
      "transitDeclarationId": "10GB00002910B75BE5",
      "isTSAD": true
    }, {
      "transitDeclarationId": "10GB00002910B75BE6",
      "sAndSMasterRefNum": "20GB01I0XLM976S004",
      "isTSAD": false
    }
  ]
}

Scenario: EIDR movement GMR example 

{
  "direction": "GB_TO_NI",
  "isUnaccompanied": false,
  "vehicleRegNum": "AB19 DEF",
  "trailerRegistrationNums": ["KF293716", "GH28372S"],
  "plannedCrossing": {
    "routeId": "178",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "eidrDeclarations": [
    {
      "traderEORI": "GB123456789012",
      "sAndSMasterRefNum": "20GB01I0XLM976S003"
    }
  ]
}

Scenario: Empty movement GMR example 

{
  "direction": "UK_OUTBOUND",
  "isUnaccompanied": false,
  "vehicleRegNum": "AB19 DEF",
  "plannedCrossing": {
    "routeId": "61",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "emptyVehicle": {
    "isOwnVehicle": true,
    "sAndSMasterRefNum": "20GB01I0XLM976S003"
  }
}

Scenario: Unaccompanied ATA carnet container movement GMR example 

{
  "direction": "UK_OUTBOUND",
  "isUnaccompanied": true,
  "containerReferenceNums": ["CSQU3054383"],
  "plannedCrossing": {
    "routeId": "61",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "ataDeclarations": [
    {
      "ataCarnetId": "SDOEFOK2982893"
    }
  ]
}

Scenario: Mixed TIR/customs movement GMR example 

{
  "direction": "GB_TO_NI",
  "isUnaccompanied": true,
  "trailerRegistrationNums": ["KF293716", "GH28372S"],
  "plannedCrossing": {
    "routeId": "178",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "sAndSMasterRefNum": "20GB01I0XLM976S001",
  "tirDeclarations": [
    {
      "tirCarnetId": "FEOKEOK092927"
    }
  ]
}

Scenario: Indirect Export Declarations movement GMR example 

{
  "direction": "NI_TO_GB",
  "isUnaccompanied": false,
  "vehicleRegNum": "AB19 DEF",
  "plannedCrossing": {
    "routeId": "179",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "indirectExportDeclarations": [
    {
      "eadMasterRefNum": "20IE01I0XLM976S003"
    },
    {
      "eadMasterRefNum": "20IE01I0XLM976S004"
    }
  ]
}

Scenario: SAD Declaration example 

{
  "direction": "UK_INBOUND",
  "isUnaccompanied": false,
  "vehicleRegNum": "AB19 DEF",
  "plannedCrossing": {
    "routeId": "61",
    "localDateTimeOfDeparture": "2021-08-11T10:58"
  },
  "sadDeclaration": {
    "sadGoods": [
      {
        "sAndSMasterRefNum": "GB12323020392"
      },
      {
        "sAndSMasterRefNum": "GB12323020393"
      }
    ]
  }
}

Name Description
direction
string
required

The direction of the movement - into or out of the UK, or between Great Britain and Northern Ireland

Limited to the following possible values:

UK_INBOUND - The movement is travelling into the UK
UK_OUTBOUND - The movement is travelling out of the UK
GB_TO_NI - The movement is travelling out of Great Britain into Northern Ireland
NI_TO_GB - The movement is travelling out of Northern Ireland into Great Britain
haulierType
string
optional

The type of haulier moving the goods

Limited to the following possible values:

STANDARD - All hauliers that are not one of the other types
FPO_ASN - Fast parcel operators that are members of the Anti-Smuggling Network
FPO_OTHER - Fast parcel operators that are not members of the ASN and are not moving goods with a Memorandum of Understanding
NATO_MOD - NATO or MoD
RMG - Royal Mail Group
ETOE - Extra-Territorial Office of Exchange
isUnaccompanied
boolean
optional

Set to true if the vehicle will not be accompanying the trailer(s) during the crossing, or if the vehicle is carrying a container that will be detached and loaded for the crossing.
vehicleRegNum
string
optional

Vehicle registration number of the vehicle that will arrive at port. If isUnaccompanied is set to false then vehicleRegNum must be provided to check-in.

Must conform to the regular expression ^[A-Z0-9-](?:[A-Z0-9 -]{1,30})?$

trailerRegistrationNums
array
optional

For vehicles carrying trailers, the trailer registration number of each trailer. If isUnaccompanied is set to true then trailerRegistrationNums or containerReferenceNums must be provided before check-in.

Must conform to the regular expression ^[A-Z0-9-](?:[A-Z0-9 -]{1,199})?$

containerReferenceNums
array
optional

For vehicles arriving with containers that will be detached and loaded, the container reference number of each container in the movement. If isUnaccompanied is set to true then trailerRegistrationNums or containerReferenceNums must be provided before check-in.

Must conform to the regular expression ^[A-Z0-9-](?:[A-Z0-9 -]{1,199})?$

plannedCrossing
object
optional

Details of the planned crossing.
routeId
string
required

The ID of the crossing route, using a routeId from the GVMS reference data

Must conform to the regular expression ^[A-Z0-9-]{1,200}$

localDateTimeOfDeparture
string
optional

The planned date and time of departure, in local time of the departure port. Must not include seconds, time zone or UTC marker

Must conform to the regular expression ^\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d$

sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers the whole trailer and not individual consignments. This applies to both ENS and EXS declarations.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

customsDeclarations
array
optional

Details of the customs declarations within this goods load.
customsDeclarationId
string
required

This is the identifier for a customs declaration from Customs Declaration Service (CDS) or CHIEF. For inbound movements declared in CDS it is a MRN, for example 19GB4S24GC3PPFGVR7. For inbound movements declared in CHIEF it is an ERN, for example 999123456C20210615. For outbound movements declared in either CDS or CHIEF it is a DUCR, for example 0GB689223596000-SE119404.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

customsDeclarationPartId
string
optional

Supported in Production environment after 5 September 2021. If a DUCR from CHIEF has been added in customsDeclarationId, this is the optional part ID. Must match the part ID for the declaration entered in CHIEF including any leading zeroes.

Must conform to the regular expression ^[0-9]{1,3}[A-Z]?$

sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers individual consignments within a trailer. This applies to both ENS and EXS declarations. If there is one, include the S&S MRN for the customs declaration above here.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

sadDeclaration
object
optional

Details of a stamped, paper-based declaration using a Single Administrative Document (SAD). Only intended for use when technical issues prevent use of Transit IT systems.
sadGoods
array
optional

References for goods loads moving under a stamped paper SAD.
sAndSMasterRefNum
string
required

The master reference number (MRN) for a Safety & Security declaration, where applicable.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

transitDeclarations
array
optional

Details of the transit declarations within this goods load.
transitDeclarationId
string
required

This is the Transit MRN issued by the Office of Departure. Must be provided.

Must conform to the regular expression ^\d{2}[A-Z]{2}[A-Z0-9]{14}$

isTSAD
boolean
required

Set to true if the transit declaration is a TSAD, otherwise set to false (for a TAD)
sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers individual Transit consignments within a trailer. This applies to both ENS and EXS declarations. If there is one, include the S&S MRN for the Transit declaration above here.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

tirDeclarations
array
optional

Details of one or more TIR Carnet declarations. Must be provided prior to check-in for TIR movements.
tirCarnetId
string
required

The TIR Carnet ID for the carnet within a TIR goods movement

Must conform to the regular expression ^.{1,200}$

sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers TIR Carnet consignments within a trailer. This applies to both ENS and EXS declarations. If there is one, include the S&S MRN for the TIR declaration above here.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

ataDeclarations
array
optional

Details of one or more ATA Carnet declarations. Must be provided prior to check-in for ATA movements.
ataCarnetId
string
required

The ATA Carnet ID for the carnet within an ATA goods movement

Must conform to the regular expression ^.{1,200}$

sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers ATA Carnet consignments within a trailer. This applies to both ENS and EXS declarations. If there is one, include the S&S MRN for the TIR declaration above here.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

eidrDeclarations
array
optional

Details of one or more EIDR declarations. Must be provided prior to check-in for EIDR movements. For movements using a specially-issued EORI, the same EORI may be entered multiple times, one entry for each ENS S&S MRN travelling under EIDR.
traderEORI
string
required

The trader's EORI

Must conform to the regular expression ^[A-Z]{2}[0-9]{12,15}$

sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers individual EIDR consignments within a trailer. This applies to both ENS and EXS declarations. If there is one, include the S&S MRN for the EIDR declaration above here.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

indirectExportDeclarations
array
optional

Details of the indirect export declarations within this goods load. Only valid for NI to GB movements where the goods originated from outside UK.
eadMasterRefNum
string
required

The master or movement reference number (MRN) of the Export Accompanying Document (EAD) for this indirect export.

Must conform to the regular expression ^\d{2}[A-Z]{2}[A-Z0-9]{14}$

emptyVehicle
object
optional

Declares that this is an empty movement and contains details about the empty movement. Must be provided prior to check-in for empty movements.
isOwnVehicle
boolean
required

Set to false if the haulier is moving the goods vehicle under a contract of carriage. Set to true if there is no contract of carriage.
sAndSMasterRefNum
string
optional

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This must be supplied when the S&S declaration covers a trailer that is moving under a contract of carriage. This applies to both ENS and EXS declarations.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

dbcDeclaration
object
optional

Declares goods moving under Declaration by Conduct. Refer to the Oral and By Conduct List published at gov.uk for details.
isOwnVehicle
boolean
required

Set to false if the haulier is moving the goods vehicle under a contract of carriage. Set to true if there is no contract of carriage.
dbcGoods
array
optional

References for a Declaration by Conduct goods load.
sAndSMasterRefNum
string
required

The master reference number or Movement Reference Number (MRN) for a Safety & Security declaration, where applicable. This may be required when the S&S declaration covers a DBC that is moving under a contract of carriage. This applies to both ENS and EXS declarations.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

exemptionDeclaration
object
optional

Declares Royal Mail Group or ETOE goods in the movement that do not require a customs declaration.
exemptedGoods
array
optional

The list of goods loads exempted from customs. Used for GB>NI RMG <£900 B2B or GB>EU FPO+MOU goods loads.
sAndSMasterRefNum
string
required

The MRN or DUCR (depending on direction) for an ENS or EXS Safety & Security declaration for this goods load.

Must conform to the regular expression ^[A-Z0-9-)(/]{1,200}$

Responses

HTTP status 202 (Accepted)

Response headers

Name Description
Notification-Message-Id
required

The messageId that will be included in a notification message created in response to this request. See above for more information about notifications.

For example: 368ed1fc-a082-41cb-a8bd-ac04cc5bdc55
Notification-Box-Id
required

The boxId to use when retrieving the notification created in response to this request. See above for more information about notifications.

For example: 3af01911-75ed-4412-a12d-ca80f626ab10

See also fraud prevention.

Error scenarios

Scenario HTTP status Code

Invalid JSON - the payload could not be parsed

400 (Bad Request)

INVALID_JSON_FORMAT

The JSON payload is not conformant with the JSON schema

400 (Bad Request)

JSON_SCHEMA_ERROR

The GMR is not in a valid state to be updated (it must be OPEN or NOT_FINALISABLE).

400 (Bad Request)

INVALID_GMR_STATE

The GMR is for a movement direction that is not yet active under current customs controls

400 (Bad Request)

NOT_YET_SUPPORTED

An attempt was made to change the direction of a GMR. This is not permitted. The GMR must be deleted and then re-created using the new direction.

400 (Bad Request)

DIRECTION_CHANGE_NOT_SUPPORTED

The user is not authorized to access the given GMR

403 (Forbidden)

No GMR could not be found with the provided GMR ID

404 (Not Found)

GMR_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section
/customs/goods-movement-system/movements/{gmrId}

Delete Goods Movement Record
DELETE

This endpoint deletes a Goods Movement Record (GMR)

Use this to delete a GMR for non-finalised movements. This will make any declaration IDs previously added to the GMR available for use in another GMR.

Authorisation

This endpoint is user-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token with the write:goods-movement-system scope.

Path parameters

Name Description
gmrId
string
required

The ID of a Goods Movement Record (GMR)

For example: 2234567890

Request headers

Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Authorization
required
 An OAuth 2.0 Bearer Token with the write:goods-movement-system scope.

For example: Bearer bb7fed3fe10dd235a2ccda3d50fb

See also fraud prevention.

Responses

HTTP status 202 (Accepted)

Response headers

Name Description
Notification-Message-Id
required

The messageId that will be included in a notification message created in response to this request. See above for more information about notifications.

For example: 368ed1fc-a082-41cb-a8bd-ac04cc5bdc55
Notification-Box-Id
required

The boxId to use when retrieving the notification created in response to this request. See above for more information about notifications.

For example: 3af01911-75ed-4412-a12d-ca80f626ab10

See also fraud prevention.

Error scenarios

Scenario HTTP status Code

The GMR is not in a valid state to be deleted (it must be OPEN or NOT_FINALISABLE).

400 (Bad Request)

INVALID_GMR_STATE

The user is not authorized to access the given GMR

403 (Forbidden)

No GMR could not be found with the provided GMR ID

404 (Not Found)

GMR_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section
/customs/goods-movement-system/reference-data

Get reference data
GET

This endpoint gets details of all reference data used by GVMS.

Reference data includes lists of:

  • Carriers operating on GVMS routes
  • Ports operating GVMS routes
  • GVMS routes (combining a carrier and a pair of ports)
  • Validation rule failure codes and descriptions

We recommend your software GETs this information once per day. The reference data is returned as a single JSON document containing all required data lists.

New carriers, routes, ports and locations will be added with effective from and to dates, so your software will have an advance view of upcoming changes. It should not offer up routes that are not yet in effect or that have expired.

Authorisation

This endpoint is open access and requires no Authorization header.

Request headers

Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json

See also fraud prevention.

Responses

HTTP status 200 (OK)

{
  "routes": [
    {
      "routeId": "102",
      "routeEffectiveFrom": "2020-01-01",
      "routeEffectiveTo": "2020-01-02",
      "departurePortId": 7014,
      "routeDirection": "UK_OUTBOUND",
      "arrivalPortId": 6085,
      "carrierId": 1
    },
    {
      "routeId": "103",
      "routeEffectiveFrom": "2020-01-01",
      "departurePortId": 7054,
      "routeDirection": "UK_OUTBOUND",
      "arrivalPortId": 1401,
      "carrierId": 2
    }
  ],
  "ports": [
    {
      "portId": 1777,
      "portRegion": "Northeast",
      "portEffectiveFrom": "2000-01-01",
      "portDescription": "Newcastle-Upon-Tyne",
      "chiefPortCode": "TYN",
      "cdsPortCode": "NCLLAOCSE",
      "officeOfTransitCustomsOfficeCode": "GB000218",
      "timezoneId": "Europe/London",
      "portCountryCode": "GB"
    },
    {
      "portId": 1824,
      "portRegion": "South",
      "portEffectiveFrom": "2000-01-01",
      "portDescription": "Newhaven",
      "chiefPortCode": "NHV",
      "cdsPortCode": "NHVNHVNHV",
      "officeOfTransitCustomsOfficeCode": "GB003250",
      "timezoneId": "Europe/London",
      "portCountryCode": "GB"
    }
  ],
  "carriers": [
    {
      "carrierId": 1,
      "carrierName": "Example carrier 1",
      "countryCode": "GB"
    },
    {
      "carrierId": 2,
      "carrierName": "Example carrier 2",
      "countryCode": "IE"
    }
  ],
  "ruleFailures": [
    {
      "ruleId": "BR005",
      "ruleDescription": "A GMR can only be used in one crossing between two customs territories"
    },
    {
      "ruleId": "BR011",
      "ruleDescription": "This Customs declaration cannot be in more than one GMR"
    }
  ]
}

Name Description
routes
array
optional

The routes covered by GVMS
routeId
string
required

The route identifier
routeDirection
string
required

The direction of the route

Limited to the following possible values:

UK_INBOUND
UK_OUTBOUND
GB_TO_NI
NI_TO_GB
routeEffectiveFrom
string
required

Date the route came into effect
departurePortId
integer
required

The id of the departure port
arrivalPortId
integer
required

The id of the arrival port
carrierId
integer
required

the id of the carrier operating that route
routeEffectiveTo
string
optional

The date the route stopped being used
ports
array
optional
portId
integer
required

The id of the port
portRegion
string
optional

The region the port is grouped into for CTC
portEffectiveFrom
string
required

The date the port came into effect
portDescription
string
required

Description of the port eg: the ports name
timezoneId
string
optional

The UTC Identifier
chiefPortCode
string
optional

The port code specific to CHIEF
cdsPortCode
string
optional

The port code specific to CDS
officeOfTransitCustomsOfficeCode
string
required

Customs office code for CTC
portEffectiveTo
string
optional

The date the port stopped being used
portCountryCode
string
required

The Country code of the associated Port

Must conform to the regular expression ^[A-Z]{2}$

isOperatingArrivedExportsProcess
boolean
optional

If true, indicates that this port is operating the arrived exports process and as such requires all customs export declarations to be pre-arrived prior to check-in. If omitted or false, indicates that this port is operating the standard exports process.
carriers
array
optional
carrierId
integer
required

The id of the carrier
carrierName
string
required

The name of the carrier
countryCode
string
optional

The country code where the carrier is registered

Must conform to the regular expression ^[A-Z]{2}$

locations
array
optional
locationId
string
required

The id of the inspection facility.
locationDescription
string
required

The name of the inspection facility location.
address
object
required

The address where the inspection facility is located.
lines
array
required

The building name or number, and street name where the inspection facility is located.
town
string
optional

The town where the inspection facility is located.
postcode
string
required

The postcode where the inspection facility is located.
locationType
string
required

The type of inspection facility; either Inland Border Facility (IBF), Border Control Post (BCP) or a facility that carries out all inspection types (ALL).

Limited to the following possible values:

IBF
BCP
ALL
supportedDirections
array
required

The directions of travel supported by the location.

Limited to the following possible values:

UK_INBOUND
UK_OUTBOUND
GB_TO_NI
NI_TO_GB
locationEffectiveFrom
string
required

The date the inspection facility location starts being used.
locationEffectiveTo
string
optional

The date the inspection facility location stops being used.
supportedInspectionTypeIds
array
required

The list of inspectionTypeIds for the types of inspections carried out.
requiredInspectionLocations
array
required

The list of portIds that the inspection facility supports.
inspectionTypes
array
optional
inspectionTypeId
string
required

The id of the type of inspection that needs to be performed on the vehicle.
description
string
required

The category of the type of inspection that needs to be performed on the vehicle e.g. CUSTOMS, DEFRA or TRANSIT.
ruleFailures
array
optional

The list of business and other possible rule failures within a GMR
ruleId
string
required
ruleDescription
string
required

Close Section

Skip to main content

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