Skip to main content

driver-find v1.6.0

A driver find service to enable external organisations to match drivers to their driving licences using their personal details

Click here to see this OpenAPI specification in JSON format.

Base URLs

Authentication

  • API Key (jwtAuth)

    • Parameter Name: Authorization, in: header. Valid JWT token issued as a result of authentication against the API Gateway.
  • API Key (apiKeyAuth)

    • Parameter Name: X-API-Key, in: header. API key used to access the service.

Find Drivers

Find drivers from at least three items of personal information.

post__v1_drivers_find

POST /v1/drivers/find

Find drivers from their personal details.

Find drivers using three or more of last name, first names, date of birth, gender and postcode.


Parameters

Name In Type Required Restrictions Description
limit header integer false Minimum: 1
Maximum: 50
Maximum the number of records to return.
offset header integer false Maximum: 49
Offset to skip the requested number of records. Used in conjunction with limit to page through results. Note requesting a value higher than the number of matched records will return no results.
body body findDriverRequest true none Search parameters - driver’s personal details.

Example Request

curl -X POST  -d '{
  "criteria": {
    "lastName": "Doe",
    "firstNames": "John Jones",
    "dateOfBirth": "1990-01-01",
    "gender": "Male",
    "postcode": "SA18 1LL"
  }
}' https://driver-vehicle-licensing.api.gov.uk/driver-find/v1/drivers/find \
 -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'limit: 10' -H 'offset: 0' -H 'Authorization: API_KEY'

Responses

Status Meaning Description Schema
200 OK Success. Returns zero or more drivers matching the supplied personal details. driversSummaryResponse
400 Bad Request Bad Request. The server could not understand the request due to invalid syntax. errorResponse
401 Unauthorized Unauthorised. errorResponse
403 Forbidden Forbidden. No access to the requested resource. errorResponse
429 Too Many Requests Too many requests in a given amount of time. errorResponse
500 Internal Server Error The service encountered an unspecified error. errorResponse

Additional common error responses are listed in the Common Error Responses page.

Example Response

Success. Returns zero or more drivers matching the supplied personal details.

{
  "results": []
}
{
  "results": [
    {
      "drivingLicenceNumber": "ABCDE123456AB1AB",
      "lastName": "Doe",
      "gender": "Male"
    }
  ]
}
{
  "results": [
    {
      "drivingLicenceNumber": "ABCDE123456AB1AB",
      "firstNames": "John",
      "lastName": "Doe",
      "gender": "Male",
      "dateOfBirth": "1990-01-01",
      "postcode": "SA18 1LL"
    }
  ]
}
{
  "results": [
    {
      "drivingLicenceNumber": "ABCDE123456AB1AB",
      "firstNames": "John",
      "lastName": "Doe",
      "gender": "Male",
      "dateOfBirth": "1990-01-01",
      "postcode": "SA18 1LL",
      "driverRedirect": true
    }
  ]
}
{
  "results": [
    {
      "drivingLicenceNumber": "JANEE123456AB1AB",
      "lastName": "Doe",
      "gender": "Female"
    },
    {
      "drivingLicenceNumber": "ABCDE123456AB1AB",
      "firstNames": "John",
      "lastName": "Doe",
      "gender": "Male",
      "dateOfBirth": "1990-01-01",
      "postcode": "SA18 1LL",
      "driverRedirect": true
    }
  ]
}

400 Response

{
  "errors": [
    {
      "status": "400",
      "code": "BRQ001",
      "detail": "Bad request"
    }
  ]
}

401 Response

{
  "errors": [
    {
      "status": "401",
      "code": "Unauthorized",
      "detail": "API Key or JWT is either not provided, expired or invalid"
    }
  ]
}

403 Response

{
  "errors": [
    {
      "status": "403",
      "code": "Forbidden",
      "detail": "Access Denied"
    }
  ]
}

429 Response

{
  "errors": [
    {
      "status": "429",
      "code": "Throttled",
      "detail": "Too many requests"
    }
  ]
}

500 Response

{
  "errors": [
    {
      "status": "500",
      "code": "ENQ000",
      "detail": "System error occurred"
    }
  ]
}

Response Headers

Status Header Type Format Description
200 X-Total-Count integer none
200 X-DVLA-Request-Id string uuid Request Id to trace the API request.
400 X-DVLA-Request-Id string uuid Request Id to trace the API request.
401 X-DVLA-Request-Id string uuid Request Id to trace the API request.
403 X-DVLA-Request-Id string uuid Request Id to trace the API request.
429 X-DVLA-Request-Id string uuid Request Id to trace the API request.
500 X-DVLA-Request-Id string uuid Request Id to trace the API request.

Schemas

x-total-count

0

The total number of driver records returned in the results.

Properties

Name Type Required Restrictions Description
anonymous integer false none The total number of driver records returned in the results.

findDriverRequest

{
  "criteria": {
    "lastName": "Doe",
    "firstNames": "John",
    "dateOfBirth": "2019-12-31",
    "gender": "Male",
    "postcode": "SA22 9FD"
  },
  "options": {
    "lastNameMatchType": "exact",
    "firstNamesMatchType": "exact",
    "searchNamesOnPreviousLicences": true,
    "searchDateOfBirthOnPreviousLicences": true,
    "includePartialPostcodesInResults": true,
    "includeImagesInResults": false,
    "orderBy": "drivingLicenceNumber"
  }
}

A driver find request containing search criteria amd options

Properties

Name Type Required Restrictions Description
criteria searchCriteria false none An object representing the information to make a search on.
options searchOptions false none An object representing the various search options used to manipulate results.

driversSummaryResponse

{
  "results": [
    {
      "drivingLicenceNumber": "ABCDE123456AB1AB",
      "firstNames": "John",
      "lastName": "Doe",
      "dateOfBirth": "2019-12-31",
      "gender": "Male",
      "postcode": "SA22 9FD",
      "driverRedirect": true,
      "image": {
        "type": "image/jpg",
        "data": "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYC..."
      }
    }
  ]
}

An response containing zero or more driver summaries.

Properties

Name Type Required Restrictions Description
results [driverSummary] true none [A summary of a driver’s details as per their current driving licence]

driverSummary

{
  "drivingLicenceNumber": "ABCDE123456AB1AB",
  "firstNames": "John",
  "lastName": "Doe",
  "dateOfBirth": "2019-12-31",
  "gender": "Male",
  "postcode": "SA22 9FD",
  "driverRedirect": true,
  "image": {
    "type": "image/jpg",
    "data": "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYC..."
  }
}

A summary of a driver’s details as per their current driving licence

Properties

Name Type Required Restrictions Description
drivingLicenceNumber drivingLicenceNumber true none A UK driving licence number.
firstNames firstNames false none The driver’s first name(s).
lastName lastName true none The driver’s last name.
dateOfBirth dateOfBirth false none The driver’s date of birth in the format YYYY-MM-DD.
gender gender true none The driver’s gender.
postcode postcode false none The postcode from the address registered to the driver’s driving licence.
driverRedirect driverRedirect false none Indicates if record was redirected from a matched previous driving licence for a driver. Details from the driver’s current driving licence are returned.
image image false none Contains the mime type and base64 encoded data of a driver’s image, only included if the ‘includeImagesInResults’ option is set to true.

gender

"Male"

The driver’s gender.

Properties

Name Type Required Restrictions Description
anonymous string false Enum: Male,Female
The driver’s gender.

Enumerated Values

Property Value
anonymous Male
anonymous Female

dateOfBirth

"2019-12-31"

The driver’s date of birth in the format YYYY-MM-DD.

Properties

Name Type Required Restrictions Description
anonymous string(date) false Min length: 10
Max length: 10
The driver’s date of birth in the format YYYY-MM-DD.

postcode

"SA22 9FD"

The postcode from the address registered to the driver’s driving licence.

Properties

Name Type Required Restrictions Description
anonymous string false Min length: 2
Max length: 8
The postcode from the address registered to the driver’s driving licence.

postcodeSearch

"SA22 9FD"

Full UK postcode, with or without a space.

Properties

Name Type Required Restrictions Description
anonymous string false Pattern: ^(([Gg][Ii][Rr]\s?0[Aa]{2}) ((([A-Za-z][0-9]{1,2})

drivingLicenceNumber

"ABCDE123456AB1AB"

A UK driving licence number.

Properties

Name Type Required Restrictions Description
anonymous string false Min length: 5
Max length: 16
A UK driving licence number.

uuid

"dbcf549a-43db-4b95-aea8-1e6b792397bb"

A UK driving licence number.

Properties

Name Type Required Restrictions Description
anonymous string(uuid) false none A UK driving licence number.

firstNamesSearch

"John"

One or more, space separated, first names of a driver to search on

Properties

Name Type Required Restrictions Description
anonymous string false Pattern: ^(?!\s*$)[a-zA-Z .‘,-]{1,38}$
Min length: 1
Max length: 38
One or more, space separated, first names of a driver to search on

firstNames

"John"

The driver’s first name(s).

Properties

Name Type Required Restrictions Description
anonymous string false none The driver’s first name(s).

lastNameSearch

"Doe"

Last name of a driver to search on

Properties

Name Type Required Restrictions Description
anonymous string false Pattern: ^(?!\s*$)[a-zA-Z .’,-]{1,43}$
Min length: 1
Max length: 43
Last name of a driver to search on

lastName

"Doe"

The driver’s last name.

Properties

Name Type Required Restrictions Description
anonymous string false none The driver’s last name.

image

{
  "type": "image/jpg",
  "data": "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYC..."
}

Contains the mime type and base64 encoded data of a driver’s image, only included if the ‘includeImagesInResults’ option is set to true.

Properties

Name Type Required Restrictions Description
type string false none Mime type of driver image
data string false none Base64 encoded driver image

driverRedirect

true

Indicates if record was redirected from a matched previous driving licence for a driver. Details from the driver’s current driving licence are returned.

Properties

Name Type Required Restrictions Description
anonymous boolean false none Indicates if record was redirected from a matched previous driving licence for a driver. Details from the driver’s current driving licence are returned.

errorResponse

{
  "errors": [
    {
      "status": "400",
      "code": "BRQ001",
      "detail": "Bad request"
    }
  ]
}

Error response containing a list of errors.

Properties

Name Type Required Restrictions Description
errors [error] false none none

error

{
  "status": "400",
  "code": "BRQ001",
  "detail": "Bad request"
}

Properties

Name Type Required Restrictions Description
status string false none HTTP status code.
code string false none DVLA reference code.
detail string false none A meaningful description of the error which has occurred.

searchOptions

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

An object representing the various search options used to manipulate results.

Properties

Name Type Required Restrictions Description
lastNameMatchType string false Enum: exact,phonetic,token
Option to specify last name match type.
firstNamesMatchType string false Enum: exact,phonetic,token
Option to specify first names match type.
searchNamesOnPreviousLicences boolean false none Option to specify whether to search previous licences with the first name(s) and last name provided.
searchDateOfBirthOnPreviousLicences boolean false none Option to specify whether to search previous licences with the date of birth provided.
includePartialPostcodesInResults boolean false none Option to specify whether to include partial postcode matches in the results (this option only has an effect on the returned results when a postcode is also supplied in the request).
includeImagesInResults boolean false none Option to specify whether to include driver photos in the results. Enforces a max page size limit of 10 results.
orderBy string false Enum: drivingLicenceNumber,name,postcode,relevance
Option to specify the order in which the results are returned.

Enumerated Values

Property Value
lastNameMatchType exact
lastNameMatchType phonetic
lastNameMatchType token
firstNamesMatchType exact
firstNamesMatchType phonetic
firstNamesMatchType token
orderBy drivingLicenceNumber
orderBy name
orderBy postcode
orderBy relevance

searchCriteria

{
  "lastName": "Doe",
  "firstNames": "John",
  "dateOfBirth": "2019-12-31",
  "gender": "Male",
  "postcode": "SA22 9FD"
}

An object representing the information to make a search on.

Properties

Name Type Required Restrictions Description
lastName lastNameSearch false none Last name of a driver to search on
firstNames firstNamesSearch false none One or more, space separated, first names of a driver to search on
dateOfBirth dateOfBirth false none The driver’s date of birth in the format YYYY-MM-DD.
gender gender false none The driver’s gender.
postcode postcodeSearch false none Full UK postcode, with or without a space.