Vehicle Enquiry Service (VES) API Guide

The VES API OpenAPI 3.0 technical specification can be found here
It is also available in JSON format

Introduction

The DVLA Vehicle Enquiry Service API is a RESTful service that provides vehicle details of a specified vehicle. It uses the vehicle registration number as input to search and provide details of the vehicle. The response data is provided in JSON format.

Register For VES API

If you would like to register to use this API, please click the button below:

Request

To consume the API, make an HTTP POST request to the following URL:

https://driver-vehicle-licensing.api.gov.uk/vehicle-enquiry/v1/vehicles

Authentication

Each request you make must be authenticated. To do this you must include a mandatory key value pair in the header of each request that is sent. - The key is x-api-key. - The value will be the API key you have been issued.

No other authentication is required for this API.

Body

Include the Vehicle Registration Number (VRN) that you wish to query in the request body like so:

{ 
  "registrationNumber": "TE57VRN" 
}

Do not include any spaces or non-alphanumeric characters in the VRN.

Example

Using cURL, a request can be made as follows:

curl -L -X POST 'https://driver-vehicle-licensing.api.gov.uk/vehicle-enquiry/v1/vehicles' \
-H 'x-api-key: REPLACE WITH YOUR API KEY' \
-H 'Content-Type: application/json' \
-d '{"registrationNumber": "TE57VRN"}'

OWASP security guidelines dictate that sensitive information should not be included in URLs. This reduces the risk of sensitive information being unnecessarily recorded in Web Server logs. The vehicle registration number is deemed sensitive information in accordance with the Information Commissioner’s Office (ICO), so is passed in the body as a POST request.

Response

A successful request should return a JSON response like the one below:

{
  "registrationNumber": "WN67DSO",
  "artEndDate": "2007-12-25",
  "co2Emissions": 0,
  "engineCapacity": 1796,
  "yearOfFirstRegistration": 2012,
  "monthOfFirstRegistration": 12,
  "yearOfFirstRegistrationWithDVLA": 2012,
  "monthOfFirstRegistrationWithDVLA": 12,
  "euroStatus": "Euro 5",
  "markedAsScrapped": true,
  "markedForExport": true,
  "fuelType": "PETROL",
  "motStatus": "No details held by DVLA",
  "motExpiry": "2008-12-25",
  "revenueWeight": 1640,
  "taxDueDate": "2017-12-25",
  "taxStatus": "Untaxed",
  "colour": "Blue",
  "make": "ROVER",
  "typeApproval": "N1",
  "wheelPlan": "NON STANDARD",
  "yearOfManufacture": 2004,
  "vehicleStatus": "Not Taxed for on Road Use",
  "dateOfLastV5CIssued": "2016-12-25",
  "realDrivingEmissions": "1",
  "automatedVehicle": false
}

Error Responses

Here is a list of the possible error responses you may receive using this API:

Status	Meaning	Description
400	Bad Request	Bad Request
404	Not Found	Vehicle Not Found
500	Internal Server Error	Internal Server Error
503	Service Unavailable	Service Unavailable

In addition to this, the common errors section gives errors that may be thrown by the surrounding framework.

Examples

Code Examples

A list of code examples can be found here.

Postman Collection

Alternatively, you can use Postman to create and execute requests.

A Postman collection containing examples for the VES API can be downloaded here.

Test Environment

Optionally, access to a test environment can be provided which will allow you to test your integration using several predefined vehicle registration numbers (VRN), including error responses. This will allow you to reliably create scenarios with specific responses from the VES API.

For Example - Using the VRN ‘ER19BAD’ results in a 400 Bad Request

Request

To call the test API, make an HTTP POST request in the same manner as normal but to the following URL:

https://uat.driver-vehicle-licensing.api.gov.uk/vehicle-enquiry/v1/vehicles

Remember to include the authentication header.

Response

If you make a request to the test API with a predetermined VRN that will return an error code, like ‘ER19BAD’, your response should look something like this:

{
  "errors": [
    {
      "status": "400",
      "code": "400",
      "title": "Bad Request",
      "detail": "Invalid format for field - vehicle registration number"
    }
  ]
}

A full list of test VRNs can be found here.

Usage Plans and Throttling Limits

Please note - only one API key can be issued per customer/company. Multiple API keys should not be requested as these are not permitted.

Access to the VES API is governed by usage plans that specify the maximum number of requests per second (RPS) that an application can make. New applications are assigned a default limit of 2 RPS. Higher limits may be available where there is a demonstrated business need.

• Requests made in excess of the allocated rate limit may be throttled or rejected.
• We also operate service-wide controls to ensure the continued availability and performance of the VES API for all users.

These two scenarios will return an HTTP status code of 429 as specified in the common errors section.

Support

Please direct any technical support queries to dvlaapiaccess@dvla.gov.uk and include VES API technical query in the subject line.