Access to Driver Data (ADD) API Guide

Introduction

The Access to Driver Data Service allows authorised consumers to retrieve the driving records of UK citizens.

It returns driver data, including current driving licence details, for a supplied driving licence number. Optionally it allows the additional retrieval of any certificate of professional competency (CPC) and/or tachograph card data held for the citizen.

Interactions with the Access to Driver Data API are via a REST interface over HTTPS. In all cases JSON is used to represent request and response data.

The functional specification of this API is detailed in the ADD OpenAPI 3.0 documentation.

The ADD OpenAPI specification is also available in JSON format.

Request

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

https://driver-vehicle-licensing.api.gov.uk/full-driver-enquiry/v1/driving-licences/retrieve

OWASP security guidelines dictate that sensitive information should not be included in URLs. In accordance with the Information Commissioner’s Office (ICO), driving licence numbers are deemed sensitive information so are passed in the body of a POST request as opposed to parameters in a GET request.

Authentication

The Access to Driver Data API implements the DVLA secure API pattern so requires usage of the DVLA Authentication API to supply a JSON Web Token (JWT) in addition to the consumer providing their individually assigned API Key.

Body

As a minimum all requests must include the driving licence number in the request body:

{
  "drivingLicenceNumber": "TCAEU610267NO9EK",
  "includeCPC": false,
  "includeTacho": false,
  "acceptPartialResponse": "false"
}

Example

Using curl, a request can be made as follows:

curl -X POST  -d '{
  "drivingLicenceNumber": "TCAEU610267NO9EK",
  "includeCPC": false,
  "includeTacho": false,
  "acceptPartialResponse": "false"
}' https://driver-vehicle-licensing.api.gov.uk/full-driver-enquiry/v1/driving-licences/retrieve \
 -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: JWT' -H 'X-Api-Key: API_KEY'

Response

A successful request will return a JSON response similar to:

Full details of the response specification is detailed in the ADD OpenAPI 3.0 documentation.

{
  "driver": {
    "drivingLicenceNumber": "TCAEU610267NO9EK",
    "firstNames": "NPBPG OYOT",
    "lastName": "TCAEUCJ",
    "gender": "Male",
    "dateOfBirth": "1967-10-26",
    "address": {
      "unstructuredAddress": {
        "line1": "78 A TEST DATA DO NOT DELIVER",
        "line5": "GREAT YARMOUTH",
        "postcode": "NR30 4BH"
      }
    }
  },
  "licence": {
    "type": "Full",
    "status": "Valid"
  },
  "entitlement": [
    {
      "categoryCode": "A",
      "categoryLegalLiteral": "A motorcycle of a power exceeding 35 kW or with a power to weight ratio exceeding 0.2 kW per kg, or A motorcycle of a power not exceeding 35 kW with a power to weight ratio not exceeding 0.2 kW per kg and derived from a vehicle of more than double its power. A motor tricycle with a power exceeding 15 kW",
      "categoryType": "Full",
      "fromDate": "2013-01-19",
      "expiryDate": "2037-10-25",
      "restrictions": [
        {
          "restrictionCode": "79(03)",
          "restrictionLiteral": "Restricted to tricycles"
        }
      ]
    }
  ],
  "endorsements": [
    {
      "offenceCode": "SP30",
      "offenceLegalLiteral": "Exceeding statutory speed limit on a public road",
      "offenceDate": "2018-04-28",
      "penaltyPoints": 3
    }
  ],
  "token": {
    "validFromDate": "1999-04-11",
    "validToDate": "2037-10-25",
    "issueNumber": "69"
  }
}

Test Environment

A test environment is provided which allows consumers to validate their integrations using several predefined driving licence numbers covering numerous scenarios including error responses.

For Example, using the driving licence number JONES712249IP6VV results in a 404 - Not Found response

Request

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

https://uat.driver-vehicle-licensing.api.gov.uk/full-driver-enquiry/v1/driving-licences/retrieve

Remember to include the authentication header.

Test Data

Test data is provided on request covering many driving licence statuses and includes drivers with additional certificate of professional competency (CPC) and/or tachograph card data.

Usage Plans and Throttling Limits

We have introduced limits on API usage rates in terms of requests per second. This applies to both individual clients and collective usage for all clients.

A consumer’s limit is set based on the usage plan that the client is subscribed to
As consumers access the API at the same time, there is an overall limit on how many requests are allowed per second in order to protect the service

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

Frequently Asked Questions

You can find answers to frequently asked questions here.

Reference Data

The relevant literals are returned alongside the codes for endorsements, entitlements and restrictions within API responses. This negates the need for the consumer to map codes to literals using reference data.

For information purposes the reference data is provided on this site.

Support

Please direct any access requests or technical support queries to ADDEnquiries@dvla.gov.uk.

Release Notes

v1.10.0 (2023-09-11)

Return additional testPass, sentenceDate and disqualifiedPendingSentence fields

v1.9.0 (2023-08-15)

Improve suppressed example response

v1.8.0 (2023-05-16)

Update response descriptions

v1.7.0 (2023-04-25)

Entitlement category literals description to state that directive indicator 4 literals are returned

v1.6.0 (2023-04-12)

Added descriptions to examples

v1.5.0 (2023-03-07)

Corrected title

v1.4.0 (2023-03-02)

Added more usage examples

v1.3.0 (2023-02-17)

Addressed internal DVLA review comments

v1.2.0 (2023-02-16)

Added security schemes
Added X-DVLA-Request-Id response header
Added missing 401 and 503 responses
Corrected errors section

v1.1.0 (2023-02-09)

Automated API spec versioning

v1.0.0 (2023-02-07)

Initial draft API