Enquiries Drivers Find Service API v1.0.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 Driver

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: 50	Restrict the number of records returned
offset	header	integer	false	Maximum: 50	Enable an API consumer to skip a certain number of records
body	body	any	true	none	Search parameters for drivers personal details.

Example Request

curl -X POST  -d '{
  "lastName": "Doe",
  "firstNames": "John",
  "dateOfBirth": "1980-09-08",
  "gender": "Male",
  "postcode": "SA2 *",
  "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 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.	gatewayErrorResponse
403	Forbidden	Forbidden. No access to the requested resource.	Inline
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",
      "placeOfBirth": "Wales",
      "gender": "Male",
      "postcode": "SA22 9FD",
      "licenceType": "Provisional",
      "licenceStatus": "Valid",
      "statusQualifier": "For re-assessment only",
      "licenceIssueNumber": "17",
      "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

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

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. Partial postcode searches can be achieved by using the ‘*’ wildcard character. The first part of the postcode with a trailing space must be provided.
options	searchOptions	false	none	none

anyOf

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none

or

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	none

driversSummaryResponse

{
  "results": [
    {
      "drivingLicenceNumber": "ABCDE123456AB1AB",
      "firstNames": "John",
      "lastName": "Doe",
      "dateOfBirth": "2019-12-31",
      "placeOfBirth": "Wales",
      "gender": "Male",
      "postcode": "SA22 9FD",
      "licenceType": "Provisional",
      "licenceStatus": "Valid",
      "statusQualifier": "For re-assessment only",
      "licenceIssueNumber": "17",
      "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",
  "placeOfBirth": "Wales",
  "gender": "Male",
  "postcode": "SA22 9FD",
  "licenceType": "Provisional",
  "licenceStatus": "Valid",
  "statusQualifier": "For re-assessment only",
  "licenceIssueNumber": "17",
  "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
placeOfBirth	placeOfBirth	false	none	Place of birth of driver
gender	gender	true	none	none
postcode	postcode	false	none	none
licenceType	licenceType	false	none	none
licenceStatus	licenceStatus	false	none	The current activation state of the licence
statusQualifier	statusQualifier	false	none	Information or restrictions relating to a Licence Status
licenceIssueNumber	licenceIssueNumber	false	none	The issue number of the licence (between 01 and 99)
driverRedirect	driverRedirect	false	none	Indicates if record was redirected from cross reference record.

placeOfBirth

"Wales"

Place of birth of driver

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Place of birth of driver

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

"SA2 *"

Postcode search parameter. Partial postcode searches can be achieved by using the ‘’ wildcard character. The first part of the postcode with a trailing space must be provided.*

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	Min length: 4 Max length: 8	Postcode search parameter. Partial postcode searches can be achieved by using the ‘*’ wildcard character. The first part of the postcode with a trailing space must be provided.

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.

licenceStatus

"Valid"

The current activation state of the licence

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	Enum: Valid,Disqualified,Revoked,Revoked for medical reasons,Surrendered,Surrendered voluntarily,Surrendered for medical reasons,Expired,Exchanged,Refused,Refused for medical reasons	The current activation state of the licence

Enumerated Values

Property	Value
anonymous	Valid
anonymous	Disqualified
anonymous	Revoked
anonymous	Revoked for medical reasons
anonymous	Surrendered
anonymous	Surrendered voluntarily
anonymous	Surrendered for medical reasons
anonymous	Expired
anonymous	Exchanged
anonymous	Refused
anonymous	Refused for medical reasons

uuid

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

Properties

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

licenceType

"Provisional"

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	Enum: Provisional,Full	none

Enumerated Values

Property	Value
anonymous	Provisional
anonymous	Full

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

licenceIssueNumber

"17"

The issue number of the licence (between 01 and 99)

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	The issue number of the licence (between 01 and 99)

statusQualifier

"For re-assessment only"

Information or restrictions relating to a Licence Status

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	Enum: For re-assessment only,Photo licence invitation sent,Short period disqualification,Until test passed,Until extended test passed,Pending sentence,For life	Information or restrictions relating to a Licence Status

Enumerated Values

Property	Value
anonymous	For re-assessment only
anonymous	Photo licence invitation sent
anonymous	Short period disqualification
anonymous	Until test passed
anonymous	Until extended test passed
anonymous	Pending sentence
anonymous	For life

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.

gatewayForbiddenErrorResponse

{
  "status": "string",
  "title": "Forbidden",
  "message": "Access Denied"
}

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.
message	string	false	none	The error response message.

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	none
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