Enquiries Driver Find Service API v1.1.0

An enquiry service for external consumers of DVLA Driver Data

Click here to see this OpenAPI specification in JSON format.

Base URLs

• https://driver-vehicle-licensing.api.gov.uk/driver-find

• https://uat.driver-vehicle-licensing.api.gov.uk/driver-find

Authentication

• HTTP Authentication, scheme: bearer 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

Single endpoint for searching and retrieving driver information

post__v1_drivers_find

POST /v1/drivers/find

Find drivers using personal details.

Parameters

Name	In	Type	Required	Restrictions	Description
limit	header	integer	false	Minimum: 1 Maximum: 10	Restrict the number of records returned
offset	header	integer	false	Maximum: 50	Enable an API consumer to skip a certain number of records. Using a value higher than the number of matched records will return no results.
body	body	findDriverRequest	true	none	Search parameters for driver’s personal details.

Example Request

curl -X POST  -d '{
  "criteria": {
    "lastName": "Doe",
    "firstNames": "John",
    "dateOfBirth": "1980-09-08",
    "gender": "Male",
    "postcode": "SA22 9FD"
  },
  "options": {
    "lastNameMatchType": "exact",
    "firstNamesMatchType": "exact",
    "searchNamesOnPreviousLicences": true,
    "searchDateOfBirthOnPreviousLicences": true,
    "includePartialPostcodesInResults": false,
    "orderBy": "drivingLicenceNumber"
  }
}' 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: Bearer {access-token}'

Responses

Status	Meaning	Description	Schema
200	OK	Success. Returns the driver(s) for the requested search by 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.	Inline
500	Internal Server Error	The service encountered an unspecified error.	Inline

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

Example Response

200 Response

{
  "results": [
    {
      "drivingLicenceNumber": "ABCDE123456AB1AB",
      "firstNames": "John",
      "lastName": "Doe",
      "dateOfBirth": "2019-12-31",
      "gender": "Male",
      "postcode": "SA22 9FD",
      "driverRedirect": true
    }
  ]
}

Response Schema

Response Headers

Status	Header	Type	Format	Description
200	X-Total-Count	integer		none

Schemas

x-total-count

0

the total number of records in the full data set

Properties

Name	Type	Required	Restrictions	Description
anonymous	integer	false	none	the total number of records in the full data set

findDriverRequest

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

Properties

Name	Type	Required	Restrictions	Description
criteria	searchCriteria	false	none	none
options	searchOptions	false	none	none

driversSummaryResponse

{
  "results": [
    {
      "drivingLicenceNumber": "ABCDE123456AB1AB",
      "firstNames": "John",
      "lastName": "Doe",
      "dateOfBirth": "2019-12-31",
      "gender": "Male",
      "postcode": "SA22 9FD",
      "driverRedirect": true
    }
  ]
}

Object containing a list of driver summaries.

Properties

Name	Type	Required	Restrictions	Description
results	[driverSummary]	false	none	[Details of a driver used to determine whether to get a driver’s full details.]

driverSummary

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

Details of a driver used to determine whether to get a driver’s full details.

Properties

Name	Type	Required	Restrictions	Description
drivingLicenceNumber	drivingLicenceNumber	true	none	A UK driving licence number. This will normally be 16 characters.
firstNames	firstNames	false	none	first name(s) of a driver
lastName	lastName	true	none	last name of a driver
dateOfBirth	date	false	none	Date in format YYYY-MM-DD
gender	gender	true	none	none
postcode	postcode	false	none	none
driverRedirect	driverRedirect	false	none	Indicates if record was redirected from cross reference record.

gender

"Male"

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	Enum: Male,Female	none

Enumerated Values

Property	Value
anonymous	Male
anonymous	Female

date

"2019-12-31"

Date in format YYYY-MM-DD

Properties

Name	Type	Required	Restrictions	Description
anonymous	string(date)	false	none	Date in format YYYY-MM-DD

postcode

"SA22 9FD"

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	Min length: 2 Max length: 8	none

postcodeSearch

"SA22 9FD"

Postcode search parameter accepted with or without 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. This will normally be 16 characters.

Properties

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

title

"Mr"

Title in full mode of address, e.g. Mr, Miss, Lord.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Title in full mode of address, e.g. Mr, Miss, Lord.

uuid

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

Properties

Name	Type	Required	Restrictions	Description
anonymous	string(uuid)	false	none	none

dateOfBirth

"1980-09-08"

The driver’s date of birth.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	Min length: 4 Max length: 10	The driver’s date of birth.

firstNamesSearch

"John"

first name(s) 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	first name(s) of a driver to search on

firstNames

"John"

first name(s) of a driver

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	first name(s) of a driver

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"

last name of a driver

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	last name of a driver

driverRedirect

true

Indicates if record was redirected from cross reference record.

Properties

Name	Type	Required	Restrictions	Description
anonymous	boolean	false	none	Indicates if record was redirected from cross reference record.

gatewayErrorResponse

{
  "status": "string",
  "title": "Unauthorized",
  "detail": "string"
}

Object containing a gateway error response.

Properties

Name	Type	Required	Restrictions	Description
status	string	false	none	HTTP status code.
title	string	false	none	The error response title.
detail	string	false	none	The error response detail.

errorResponse

{
  "errors": [
    {
      "status": "string",
      "code": "string",
      "detail": "string"
    }
  ]
}

Object containing a list of error responses.

Properties

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

error

{
  "status": "string",
  "code": "string",
  "detail": "string"
}

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": false,
  "orderBy": "drivingLicenceNumber"
}

Properties

Name	Type	Required	Restrictions	Description
lastNameMatchType	string	false	Enum: exact,phonetic,token	none
firstNamesMatchType	string	false	Enum: exact,phonetic,token	none
searchNamesOnPreviousLicences	boolean	false	none	none
searchDateOfBirthOnPreviousLicences	boolean	false	none	none
includePartialPostcodesInResults	boolean	false	none	This option only has an effect on the returned results when a postcode is also supplied in the request
orderBy	string	false	Enum: drivingLicenceNumber,name,postcode,relevance	none

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": "1980-09-08",
  "gender": "Male",
  "postcode": "SA22 9FD"
}

Properties

Name	Type	Required	Restrictions	Description
lastName	lastNameSearch	false	none	last name of a driver to search on
firstNames	firstNamesSearch	false	none	first name(s) of a driver to search on
dateOfBirth	dateOfBirth	false	none	The driver’s date of birth.
gender	gender	false	none	none
postcode	postcodeSearch	false	none	Postcode search parameter accepted with or without space.