DVLA Driving Licence Renewal API v0.1.3

Allows DVLA partners to support driving licence renewal applications

Click here to see this OpenAPI specification in JSON format.

Base URLs

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

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

Terms of service Email: DVLA Digital Services Support

Authentication

• HTTP Authentication, scheme: bearer Valid JWT token issued as a result of authentication using the DVLA Authentication API

• API Key (apiKeyAuth)

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

v1-drivers-renewal

POST-Drivers-Renewal

POST /v1/drivers/renewal

Submit a driving licence renewal application

Parameters

Name	In	Type	Required	Restrictions	Description
X-Correlation-ID	header	string	false	none	Link log messages to a specific application request
body	body	DrivingLicenceRenewalRequest	true	none	Application being submitted

Example Request

curl -X POST  -d '{
  "handler": {
    "originatorId": "POL",
    "transactionID": "123456789012345678901234",
    "userId": "john-smith",
    "branchId": "a123",
    "terminalId": "1581239",
    "localDateTime": "2022-01-01T09:00:00Z"
  },
  "driverNumber": "MCADI801206HZ9HM",
  "transactionType": "TYRR",
  "applicationReferenceNumber": "98269432242880068489880451264",
  "feePaid": 1575,
  "investigationRequired": true,
  "dateOfBirth": "1970-01-01T09:00:00Z",
  "daytimePhone": "01234567890",
  "photo": {
    "photoOverride": false,
    "icaoCompliant": true,
    "eyesOpen": true,
    "exposure": true,
    "frontalView": true,
    "greyscaleDensity": true,
    "uniformLighting": true,
    "headWidth": true,
    "headLength": true,
    "widthHeightRatio": true,
    "resolution": true,
    "verticalPosition": true,
    "horizontallyCentered": true,
    "photographImage": "BASE64JPEGSTRING"
  },
  "signatureImage": "BASE64IMAGEDATASTRING",
  "licenceStatus": {
    "photocardSurrendered": true,
    "photocardIssueNumber": "12",
    "counterpartSurrendered": false,
    "counterpartIssueNumber": "3",
    "lostMarker": false,
    "stolenMarker": false,
    "defacedMarker": false,
    "destroyedMarker": false
  },
  "twoDBarcode": "9826943224281001848986045116301GAIR                          GERARD                        SWAN                          34 SAXON CLOSE                SA1 1SD ",
  "updateAddress": {
    "unstructuredAddress": {
      "line1": "123 Any Street",
      "postTown": "Anytown",
      "postcode": "SA1 1AA"
    }
  },
  "photoCardFront": "BASE64JPEGSTRING",
  "photoCardBack": "BASE64JPEGSTRING",
  "organDonor": {
    "anyOrgans": false,
    "kidneys": true,
    "liver": true,
    "heart": false,
    "cornea": false,
    "pancreas": true,
    "lungs": false
  }
}' https://uat.driver-vehicle-licensing.api.gov.uk/drivers-renewal/v1/drivers/renewal \
 -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'X-Correlation-ID: b5d9b2bd-6e8f-4275-bdd3-c8086fe09c52' -H 'Authorization: Bearer {access-token}' -H 'X-API-Key: API_KEY'

Responses

Status	Meaning	Description	Schema
202	Accepted	Application accepted	DrivingLicenceRenewalResponse
400	Bad Request	Invalid parameters	BadRequestErrorResponse
500	Internal Server Error	Unexpected error	InternalServerErrorResponse

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

Example Response

202 Response

{
  "transactionId": "0922b8b5-a75b-4038-ae27-44bb36062af0"
}

Schemas

DrivingLicenceRenewalRequest

{
  "handler": {
    "originatorId": "POL",
    "transactionID": "123456789012345678901234",
    "userId": "john-smith",
    "branchId": "a123",
    "terminalId": "1581239",
    "localDateTime": "2022-01-01T09:00:00Z"
  },
  "driverNumber": "MCADI801206HZ9HM",
  "transactionType": "TYRR",
  "applicationReferenceNumber": "98269432242880068489880451264",
  "feePaid": 1575,
  "investigationRequired": true,
  "dateOfBirth": "1970-01-01T09:00:00Z",
  "daytimePhone": "01234567890",
  "photo": {
    "photoOverride": false,
    "icaoCompliant": true,
    "eyesOpen": true,
    "exposure": true,
    "frontalView": true,
    "greyscaleDensity": true,
    "uniformLighting": true,
    "headWidth": true,
    "headLength": true,
    "widthHeightRatio": true,
    "resolution": true,
    "verticalPosition": true,
    "horizontallyCentered": true,
    "photographImage": "BASE64JPEGSTRING"
  },
  "signatureImage": "BASE64IMAGEDATASTRING",
  "licenceStatus": {
    "photocardSurrendered": true,
    "photocardIssueNumber": "12",
    "counterpartSurrendered": false,
    "counterpartIssueNumber": "3",
    "lostMarker": false,
    "stolenMarker": false,
    "defacedMarker": false,
    "destroyedMarker": false
  },
  "twoDBarcode": "9826943224281001848986045116301GAIR                          GERARD                        SWAN                          34 SAXON CLOSE                SA1 1SD ",
  "updateAddress": {
    "unstructuredAddress": {
      "line1": "123 Any Street",
      "postTown": "Anytown",
      "postcode": "SA1 1AA"
    }
  },
  "photoCardFront": "BASE64JPEGSTRING",
  "photoCardBack": "BASE64JPEGSTRING",
  "organDonor": {
    "anyOrgans": false,
    "kidneys": true,
    "liver": true,
    "heart": false,
    "cornea": false,
    "pancreas": true,
    "lungs": false
  }
}

request

Properties

Name	Type	Required	Restrictions	Description
handler	Handler	true	none	Request meta data
drivingLicenceNumber	string	false	Pattern: ^[a-zA-Z0-9]*$ Min length: 16 Max length: 16	A UK driving licence number
transactionType	string	true	Enum: TYRR,TYRPC	A field denoting the transaction type TYRR for a renewal reminder TYRPC for a photocard renewal
applicationReferenceNumber	string	false	Max length: 29	The application reference number as detailed in the barcode part of a D798 form
feePaid	integer	true	Maximum: 999999	The total amount taken from the customer at the counter for this transaction in pence
investigationRequired	boolean	false	none	When the indicator is set to Y, the clerk has decided that the DVLA should investigate the application
dateOfBirth	string(date)	false	none	The customer’s date of birth
daytimePhone	string	false	Min length: 1 Max length: 30	A daytime UK contact number
photo	Photo	true	none	Photo image and qualify checks
signatureImage	string	false	none	Driver signature contentMediaType: “image/[png
updateAddress	UpdateAddress	false	none	If supplied, at least one and only one of a Structured PAF, Unstructured Address lines or BFPO address must be provided - oneOf notation avoided due to not being ubiquitously supported. This is the address to be used for external dispatch. This will be converted into a standard printable address format for output in the address window. For bulk mail handling, the majority (90% at the time of writing) of dispatch addresses need to match valid Royal Mail address with corresponding DPS and mailsort code information.
licenceStatus	LicenceStatus	false	none	Licence Data
twoDBarcode	string	false	Max length: 159	159 character representation of the contents of the Reminder barcode
organDonor	OrganDonor	false	none	Organ Donor
photoCardFront	string	false	none	Photocard front - only required for Photocard (non Reminder) applications. contentMediaType: "image/jpeg”, “contentEncoding”: “base64”
photoCardBack	string	false	none	Photocard back - only required for Photocard (non Reminder) applications. contentMediaType: “image/jpeg”, “contentEncoding”: “base64”

Enumerated Values

Property	Value
transactionType	TYRR
transactionType	TYRPC

DrivingLicenceRenewalResponse

{
  "transactionId": "0922b8b5-a75b-4038-ae27-44bb36062af0"
}

Driving Licence Renewal Response component

Properties

Name	Type	Required	Restrictions	Description
transactionId	TransactionID	true	none	Value used to uniquely identify a transaction within the client system, and to identify a request/response pair
dateTimeReceived	string(date-time)	true	none	The date and time the request message was received by the DVLA service

Handler

{
  "originatorId": "POL",
  "transactionId": "123456789012345678901234",
  "userId": "john-smith",
  "branchId": "a123",
  "terminalId": "1581239",
  "localDateTime": "2022-01-01T09:00:00Z"
}

Request meta data

Properties

Name	Type	Required	Restrictions	Description
originatorId	string	false	Max length: 256	Identifies the intermediary organisation supporting the application
transactionId	TransactionID	false	none	Value used to uniquely identify a transaction within the client system, and to identify a request/response pair
userId	string	false	Max length: 256	This is the identifier for the Post Office clerk who carried out the enrolment in the branch
branchId	string	false	Max length: 256	Optionally identifies the branch at which the application took place
terminalId	string	false	Max length: 256	This is the terminal ID workstation that was used during enrolment
localDateTime	string(date-time)	false	none	The branch date and time stamp when the transaction commenced

OrganDonor

[
  {
    "anyOrgans": true
  }
]

Organ Donor

Properties

Name	Type	Required	Restrictions	Description
anyOrgans	boolean	false	none	Any Organs
kidneys	boolean	false	none	Kidneys
liver	boolean	false	none	Liver
heart	boolean	false	none	Heart
cornea	boolean	false	none	Cornea
pancreas	boolean	false	none	Pancreas
lungs	boolean	false	none	lungs

Photo

[
  {
    "photographImage": "BASE64JPEGSTRING",
    "photoOverride": false,
    "icaoCompliant": true,
    "eyesOpen": true,
    "exposure": true,
    "frontalView": true,
    "greyscaleDensity": true,
    "uniformLighting": true,
    "headWidth": true,
    "headLength": true,
    "widthHeightRatio": true,
    "resolution": true,
    "verticalPosition": true,
    "horizontallyCentered": true
  }
]

Photo image and qualify checks

Properties

Name	Type	Required	Restrictions	Description
photographImage	string	false	none	Driver photograph contentMediaType: “image/jpeg”, “contentEncoding”: “base64”
photoOverride	boolean	false	none	When the indicator is set to Y, the clerk has indicated a concern with photo compliance
icaoCompliant	boolean	false	none	Flag to indicate whether or not the facial image is ICAO compliant
eyesOpen	boolean	false	none	Flag to indicate whether eyes are open
exposure	boolean	false	none	Flag to indicate whether exposure levels are correct
frontalView	boolean	false	none	Flag to indicate whether the image is a frontal view
greyscaleDensity	boolean	false	none	Flag to indicate whether the greyscale density is correct
uniformLighting	boolean	false	none	Flag to indicate whether lighting is uniform across face image
headWidth	boolean	false	none	Flag to indicate whether head width is within acceptable range
headLength	boolean	false	none	Flag to indicate whether head length is within acceptable range
widthHeightRatio	boolean	false	none	Flag to indicate whether face width to height ratio is correct
resolution	boolean	false	none	Flag to indicate whether image resolution is acceptable
verticalPosition	boolean	false	none	Flag to indicate whether vertical image position is acceptable
horizontallyCentered	boolean	false	none	Flag to indicate whether image is horizontally centered

LicenceStatus

{
  "photocardSurrendered": true,
  "photocardIssueNumber": "12",
  "counterpartSurrendered": false,
  "counterpartIssueNumber": "3",
  "lostMarker": false,
  "stolenMarker": false,
  "defacedMarker": false,
  "destroyedMarker": false
}

Licence Data

Properties

Name	Type	Required	Restrictions	Description
photocardSurrendered	boolean	false	none	Whether the photo card part of the licence has been surrendered to a third party
photocardIssueNumber	string	false	Min length: 1 Max length: 2	The licence photo card issue number
counterpartSurrendered	boolean	false	none	A flag denoting whether the licence counterpart has been surrendered to a third party
counterpartIssueNumber	string	false	Min length: 1 Max length: 3	The licence counterpart issue number
lostMarker	boolean	false	none	A flag denoting whether the licence has been lost or not
stolenMarker	boolean	false	none	A flag denoting whether the licence has been stolen or not
defacedMarker	boolean	false	none	A flag denoting whether the licence has been defaced or not
destroyedMarker	boolean	false	none	A flag denoting whether the licence has been destroyed or not

UpdateAddress

{
  "structuredAddress": {
    "buildingName": "MONOMARK HOUSE",
    "buildingNumber": "54",
    "dependentThoroughfareName": "OLD GLOUCESTER STREET",
    "thoroughfareName": "OLD GLOUCESTER ROAD",
    "doubleDependentLocality": "DOUBLE CROFT",
    "dependentLocality": "CAMDEN",
    "postTown": "LONDON",
    "postcode": "WC1N 1AA",
    "country": "England",
    "language": "EN",
    "dps": "1A",
    "uprn": "5138439",
    "udprn": "26246299"
  }
}

If supplied, at least one and only one of a Structured PAF, Unstructured Address lines or BFPO address must be provided - oneOf notation avoided due to not being ubiquitously supported. This is the address to be used for external dispatch. This will be converted into a standard printable address format for output in the address window. For bulk mail handling, the majority (90% at the time of writing) of dispatch addresses need to match valid Royal Mail address with corresponding DPS and mailsort code information.

Properties

Name	Type	Required	Restrictions	Description
structuredAddress	StructuredAddress	false	none	Address containing Royal Mail PAF fields for a single address including DPS, which if provided allows for postal cost savings alongside Mailsort information added upon print. Note that at least one of the following fields must be provided with a non-empty value in order to provide a useful address to print for delivery to a recipient: departmentName, organisationName, poBoxNumber, buildingNumber, subBuildingName, buildingName, thoroughfareName, doubleDependentLocality, dependentThoroughfareName, dependentLocality, postTown
unstructuredAddress	UnstructuredAddress	false	none	Address manually entered by a user
bfpoAddress	BfpoAddress	false	none	British Forces Post Office address, where BFPO Number is mandatory from the current list of operational BFPO numbers, and postcode is optional

UnstructuredAddress

{
  "line1": "This is a line 1",
  "line2": "VIRTUAL OFFICE",
  "line3": "FLAT 99A",
  "line4": "COPMANY HOUSE",
  "postTown": "NEWTOWN",
  "postcode": "WC1N 1ZZ"
}

Address manually entered by a user

Properties

Name	Type	Required	Restrictions	Description
line1	string	true	Min length: 1 Max length: 45	none
line2	string	false	Max length: 45	none
line3	string	false	Max length: 45	none
line4	string	false	Max length: 45	none
postTown	string	false	Max length: 45	none
postcode	string	true	Min length: 1 Max length: 10	none
language	Language	false	none	Optionally specifies address language ISO code, CY for Welsh, EN for English
dps	DPS	false	none	Royal Mail Delivery Point Suffix where matched to a PAF address. Uniquely identifies each address (Delivery Point) within a single postcode

StructuredAddress

{
  "poBoxNumber": "PO Box 21",
  "organisationName": "BRITISH LANDMARKS",
  "departmentName": "VIRTUAL OFFICE",
  "subBuildingName": "FLAT 2A",
  "buildingName": "LANDMARK HOUSE",
  "buildingNumber": "270",
  "dependentThoroughfareName": "OLD GLOUCESTER STREET",
  "thoroughfareName": "OLD GLOUCESTER ROAD",
  "doubleDependentLocality": "DOUBLE CROFT",
  "dependentLocality": "CAMDEN",
  "postTown": "LONDON",
  "postcode": "WC1N 1AA",
  "country": "England",
  "language": "EN",
  "dps": "1A",
  "uprn": "5138439",
  "udprn": "26246299"
}

*Address containing Royal Mail PAF fields for a single address including DPS, which if provided allows for postal cost savings alongside Mailsort information added upon print. Note that at least one of the following fields must be provided with a non-empty value in order to provide a useful address to print for delivery to a recipient: departmentName, organisationName, poBoxNumber, buildingNumber, subBuildingName, buildingName, thoroughfareName, doubleDependentLocality, dependentThoroughfareName, dependentLocality, postTown *

Properties

Name	Type	Required	Restrictions	Description
poBoxNumber	string	false	Max length: 6	PO Box number. When the Post Office (PO) Box number field is populated, it is typically prefixed with ‘PO BOX ’ upon output. Note that the PO Box details can occasionally consist of a combination of numbers and letters e.g. HK860. PO Box Numbers are only allocated to Large Users
organisationName	string	false	Max length: 60	Name of the organisation registered at this address
departmentName	string	false	Max length: 30	Used to supplement Organisation Name to identify a department within the organisation
subBuildingName	string	false	Max length: 30	When a premise is split into individual units such as flats, apartments or business units. Cannot be present without either building_name or building_number
buildingName	string	false	Max length: 50	Name of residential or commercial premise
buildingNumber	string	false	Max length: 4	Number to identify premise on a thoroughfare or dependant thoroughfare. Limited to 4 numbers within PAF - see PAF programmers guide for locating non-numerical building numbers
dependentThoroughfareName	string	false	Max length: 80	Used to supplement thoroughfare. When a thoroughfare name is used twice in the same Post Town, the dependant thoroughfare is added to uniquely identify a delivery point
thoroughfareName	string	false	Max length: 80	A main road or passageway. When the locality information does not identify the location of an address there will be thoroughfare information available. Includes thoroughfare name (60) and type descriptor (20) combined, where common descriptors such as road, avenue, court are provided separately in PAF which can help with abbreviation
doubleDependentLocality	string	false	Max length: 35	Used to distinguish between similar or same thoroughfares within a dependent locality, e.g. small villages
dependentLocality	string	false	Max length: 35	Dependent locality areas may define an area within a post town
postTown	string	true	Max length: 30	A Post Town is mandatory for delivery of mail to a Delivery Point. This is not necessarily the nearest town geographically, but a routing instruction to the Royal Mail delivery office sorting mail for that Delivery Point
postcode	string	true	Max length: 8	Postcode including space. PAF postcodes are max length 7 without space, but for consistency and ease of use storage, transmission and display formats should include it
country	string	false	Max length: 64	Optionally specific address country, e.g ‘Wales’
language	Language	false	none	Optionally specifies address language ISO code, CY for Welsh, EN for English
dps	DPS	false	none	Royal Mail Delivery Point Suffix where matched to a PAF address. Uniquely identifies each address (Delivery Point) within a single postcode
uprn	string	true	Max length: 12	Unique Property Reference Number. Ordnance Survey unique alphanumeric identifier for every spatial address in Great Britain
udprn	string	false	Max length: 8	Unique Delivery Point Reference Number. An eight digit unique numeric code for delivery points on the PAF File as allocated by Royal Mail

BfpoAddress

{
  "line1": "12345678 LCPL B Jones",
  "line2": "B Company",
  "line3": "1 Loamshire Regt",
  "line4": "HMS Dauntless",
  "bfpoNumber": 5432,
  "postcode": "BF1 1ZZ"
}

British Forces Post Office address, where BFPO Number is mandatory from the current list of operational BFPO numbers, and postcode is optional

Properties

Name	Type	Required	Restrictions	Description
line1	string	true	Min length: 1 Max length: 45	Free text, expected to be UNIT or REGIMENT.
line2	string	false	Min length: 1 Max length: 45	Free text, expected to be OPERATION.
line3	string	false	Min length: 1 Max length: 45	Free text, expected to be BARRACKS or CAMP or RAF STATION or NAVAL SHIP (if applicable).
line4	string	false	Min length: 1 Max length: 45	Free text
bfpoNumber	integer	true	Minimum: 1 Maximum: 9999	none
postcode	string	false	Min length: 1 Max length: 10	none

TransactionID

"string"

Value used to uniquely identify a transaction within the client system, and to identify a request/response pair

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	Min length: 1 Max length: 256	Value used to uniquely identify a transaction within the client system, and to identify a request/response pair

Language

"CY"

Optionally specifies address language ISO code, CY for Welsh, EN for English

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	Enum: EN,CY	Optionally specifies address language ISO code, CY for Welsh, EN for English

Enumerated Values

Property	Value
anonymous	EN
anonymous	CY

DPS

"9Z"

Royal Mail Delivery Point Suffix where matched to a PAF address. Uniquely identifies each address (Delivery Point) within a single postcode

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	Max length: 2	Royal Mail Delivery Point Suffix where matched to a PAF address. Uniquely identifies each address (Delivery Point) within a single postcode

BadRequestErrorResponse

{
  "errors": [
    {
      "status": "400 BAD_REQUEST",
      "code": "NotEmpty",
      "title": "standardParams.recipientName",
      "detail": "Recipient name field must not be empty."
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
errors	[BadRequestError]	false	none	Array of Error objects

InternalServerErrorResponse

{
  "errors": [
    {
      "status": "500 INTERNAL_SERVER_ERROR",
      "code": "2",
      "title": "Unexpected Exception.",
      "detail": "An unexpected exception was raised by the service with Error Id: 16011497-35a9-4eef-885b-e5fe552693b8"
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
errors	[InternalServerError]	false	none	Array of Error objects

BadRequestError

{
  "status": "400 BAD_REQUEST",
  "code": "InvalidRequiredHeader",
  "title": "Invalid Header",
  "detail": "Recipient name field must not be empty."
}

Properties

Name	Type	Required	Restrictions	Description
status	string	false	none	The error HTTP response status
code	string	false	none	An error code that relates to a specific error condition
title	string	false	none	The error title
detail	string	false	none	Further detail about the error

InternalServerError

{
  "status": "500 INTERNAL_SERVER_ERROR",
  "code": "2",
  "title": "Unexpected Exception.",
  "detail": "An unexpected exception was raised by the service with Error Id: 16011497-35a9-4eef-885b-e5fe552693b8"
}

Properties

Name	Type	Required	Restrictions	Description
status	string	false	none	The error HTTP response status
code	string	false	none	An error code that relates to a specific error condition
title	string	false	none	Error title
detail	string	false	none	Error detail