Drivers Find API Guide

Introduction

The Find Driver Service allows authorised external clients to retrieve summary driver data with fine-grained search criteria.

It returns driver summary data, including driving licence number, last name and gender, for the supplied search criteria.

Interactions with the Drivers Find 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 Drivers Find OpenAPI 3.0 documentation.

The Find Driver 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/driver-find

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 Find Driver 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

The request body comprises 2 fields: criteria and options. At a minimum, a request must contain a criteria object with any 3 of the following example fields:

{
  "firstNames": "Barry",
  "lastName": "Williams",
  "dateOfBirth": "1990-06-01",
  "postcode": "WD2 2SL",
  "gender": "Male"
}

The options field can contain any combination of the fields shown in the following example, with default values:

{
  "lastNameMatchType": "exact",
  "firstNamesMatchType": "phonetic",
  "searchNamesOnPreviousLicences": true,
  "searchDateOfBirthOnPreviousLicences": true,
  "includeImagesInResults": false,
  "includePartialPostcodesInResults": true,
  "orderBy": "relevance"
}

Full request example with criteria and default options

{
  "criteria": {
    "firstNames": "Barry",
    "lastName": "Williams",
    "dateOfBirth": "1990-06-01",
    "postcode": "WD2 2SL",
    "gender": "Male"
  },
  "options": {
    "lastNameMatchType": "exact",
    "firstNamesMatchType": "phonetic",
    "searchNamesOnPreviousLicences": true,
    "searchDateOfBirthOnPreviousLicences": true,
    "includeImagesInResults": false,
    "includePartialPostcodesInResults": true,
    "orderBy": "relevance"
  }
}

Matching types

Exact

A matching type of exact will match a term exactly, for example a request with like:

{
  "criteria": {
    ...
    "firstNames": "Stephen"
  },
  "options": {
    "firstNamesMatchType": "exact"
  }
}

will only match records with the exact firstNames value of “Stephen”.

Phonetic

A matching type of phonetic will match records with phonetically similar terms, for example a request like:

{
  "criteria": {
    ...
    "lastName": "Stevens"
  },
  "options": {
    "lastNameMatchType": "phonetic"
  }
}

will match records with a lastName of “Stevens” but also “Stephens”.

Token

A matching type of token will partially match terms, for example a request like:

{
  "criteria": {
    ...
    "lastName": "Porter"
  },
  "options": {
    "lastNameMatchType": "token"
  }
}

will match records with a lastName of “Porter” but also “Porter-Burton” and “Burton-Porter”.

Example

Using curl, a request can be made as follows:

curl -X POST -d '{
  "firstNames": "Barry",
  "lastName": "Williams",
  "gender": "Male"
}' https://driver-vehicle-licensing.api.gov.uk/driver-find/v1/drivers/find \
 -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 Drivers Find OpenAPI 3.0 documentation.

{
  "results": [
    {
      "drivingLicenceNumber": "WILLI858309EY4LE",
      "lastName": "Williams",
      "gender": "Male"
    }
  ]
}

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 HALL9655293DH5RO results in a 400 - 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/driver-find

Remember to include the authentication header.

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.

1. A consumer’s limit is set based on the usage plan that the client is subscribed to
2. 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.

Support

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

Release Notes

v1.7.0 (2023-05-04)

• Improved orderBy description for postcode
• Added fullName search option

v1.6.0 (2023-04-25)

• Added includeImagesInResponse field to request
• Added image field to response

v1.5.0 (2022-12-21)

• Changed title

v1.4.0 (2022-05-13)

• Increased limit maximum
• Changed JWT authentication to header

v1.3.0 (2022-03-10)

• Added automated spec publishing
• Removed partial postcode ref in spec description
• Changed includePartialPostcodesInResults default to true
• Changed max offset to 49
• Improved orderBy description

v1.2.0 (2021-11-26)

• Example and description improvements

v1.1.0 (2021-10-28)

• Minor description changes

v1.0.0 (2021-09-02)

• Initial draft API