Skip to main content

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

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