driver-find v1.5.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

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

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

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,
    "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
    }
  ]
}

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
}

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 form a matched previous driving licence for a driver. Details from the driver’s current driving licence are returned.

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.

driverRedirect

true

Indicates if record was redirected form 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 form 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,
  "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).
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.