kadoe-service v1.0.0

Service to retrieve a vehicle’s Keeper at Date of Event (KADOE)

Click here to see this OpenAPI specification in JSON format.

Base URLs

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

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

Email: DVLA API Team

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

getVehicleKeeper

POST /v1/vehicle-keeper

Retrieve Keeper at Date of Event for a vehicle.

Parameters

Name	In	Type	Required	Restrictions	Description
body	body	KadoeRequest	true	none	The vehicle’s registration number or chassis number, the reason for the enquiry, and the event date time.

Example Request

curl -X POST  -d '{
  "enquirerId": "AA123",
  "reasonCode": "00AC",
  "registrationNumber": "AA19AAA",
  "eventDate": "2023-07-04T00:00:00.000Z",
  "referenceNumber": "co6wz38alj0h"
}' https://driver-vehicle-licensing.api.gov.uk/kadoe/v1/vehicle-keeper \
 -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {access-token}'

Responses

Status	Meaning	Description	Schema
200	OK	Keeper details at date of event	KadoeResponse
400	Bad Request	Bad Request	ErrorResponse
401	Unauthorized	Unauthorized	None
403	Forbidden	Forbidden	None
404	Not Found	Not found	ErrorResponse
500	Internal Server Error	Internal Server Error	ErrorResponse
503	Service Unavailable	Service Unavailable	None

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

Example Response

Keeper details at date of event

{
  "registrationNumber": "XYZ1",
  "make": "PEUGEOT",
  "model": "307 CC",
  "fleetNumber": 4,
  "colour": "Black",
  "taxStatus": "Taxed",
  "keeper": {
    "title": "MR",
    "firstNames": "JOE",
    "lastName": "BLOGGS",
    "address": {
      "line1": "123 EXAMPLE STREET",
      "line2": "EXAMPLE TOWN",
      "line5": "EXAMPLE CITY",
      "postcode": "SA1 1AA"
    }
  }
}

{
  "registrationNumber": "XYZ1",
  "make": "PEUGEOT",
  "model": "307 CC",
  "fleetNumber": 4,
  "colour": "Black",
  "taxStatus": "Taxed",
  "keeper": {
    "companyName": "EXAMPLE & SONS",
    "address": {
      "line1": "123 EXAMPLE STREET",
      "line2": "EXAMPLE TOWN",
      "line5": "EXAMPLE CITY",
      "postcode": "SA1 1AA"
    }
  }
}

400 Response

{
  "errors": [
    {
      "status": 400,
      "code": "ENQ102",
      "detail": "Invalid format for field - vehicle registration number"
    }
  ]
}

Not found

{
  "errors": [
    {
      "status": 404,
      "code": "ENV002",
      "detail": "Details unavailable response to follow"
    }
  ]
}

{
  "errors": [
    {
      "status": 404,
      "code": "ENV003",
      "detail": "No information found"
    }
  ]
}

Internal Server Error

{
  "errors": [
    {
      "status": 500,
      "code": "ENV004",
      "detail": "System returned error"
    }
  ]
}

Schemas

KadoeRequest

{
  "enquirerId": "AA001",
  "linkProviderId": "A01",
  "reasonCode": "00ET",
  "registrationNumber": "XYZ1",
  "chassisVin": "VF33BRFNC83846199",
  "eventDate": "2006-05-26",
  "referenceNumber": "ABC123"
}

Properties

Name	Type	Required	Restrictions	Description
enquirerId	string	true	none	Identifier for the enquirer.
linkProviderId	string	false	none	Identifier for the link provider, should there be one.
reasonCode	string	true	none	Code indicating the reason for the enquiry.
registrationNumber	RegistrationNumber	false	none	Vehicle’s registration number.
chassisVin	ChassisVin	false	none	Vehicle’s chassis identification number.
eventDate	string(YYYY-MM-DD)	true	none	The date of event in format YYYY-MM-DD.
referenceNumber	string	true	none	Alpha-numeric reference provided by the enquirer.

KadoeResponse

{
  "registrationNumber": "XYZ1",
  "chassisVin": "VF33BRFNC83846199",
  "make": "PEUGEOT",
  "model": "307 CC",
  "fleetNumber": 4,
  "colour": "Black",
  "secondaryColour": "Red",
  "keeper": {
    "title": "MR",
    "firstNames": "Simon",
    "lastName": "Fleet",
    "companyName": "Microsoft",
    "address": {
      "line1": "DVLA Long View Rd",
      "line2": "Morriston",
      "line3": "Clase",
      "line4": "Swansea",
      "line5": "West Glamorgan",
      "postcode": "SA6 7JL"
    }
  },
  "message": "Vehicle stolen at date of event",
  "taxStatus": "Taxed",
  "seatingCapacity": 5,
  "bodyType": "Box Van",
  "taxClass": "Disabled"
}

Properties

Name	Type	Required	Restrictions	Description
registrationNumber	RegistrationNumber	false	none	Vehicle’s registration number.
chassisVin	ChassisVin	false	none	Vehicle’s chassis identification number.
make	string	false	none	The make of the vehicle.
model	string	false	none	The model of the vehicle.
fleetNumber	string	false	none	The assigned fleet number of the vehicle.
colour	string	false	none	The vehicle’s colour.
secondaryColour	string	false	none	Another colour present on the vehicle.
keeper	Keeper	false	none	none
message	string	false	none	Information message for stolen, scrapped and exported vehicles.
taxStatus	string	false	Enum: Not Taxed for on Road Use,SORN,Untaxed,Taxed	The current tax status of the vehicle.
seatingCapacity	integer(int32)	false	none	The seating capacity of the vehicle.
bodyType	string	false	none	The body type of the vehicle.
taxClass	string	false	none	The tax class of the vehicle.

Enumerated Values

Property	Value
taxStatus	Not Taxed for on Road Use
taxStatus	SORN
taxStatus	Untaxed
taxStatus	Taxed

Keeper

{
  "title": "MR",
  "firstNames": "Simon",
  "lastName": "Fleet",
  "companyName": "Microsoft",
  "address": {
    "line1": "DVLA Long View Rd",
    "line2": "Morriston",
    "line3": "Clase",
    "line4": "Swansea",
    "line5": "West Glamorgan",
    "postcode": "SA6 7JL"
  }
}

Properties

Name	Type	Required	Restrictions	Description
title	string	false	none	Title of the person who is the registered keeper of the vehicle.
firstNames	string	false	none	First names of the person who is the registered keeper of the vehicle.
lastName	string	false	none	Last name of the person who is the registered keeper of the vehicle.
companyName	string	false	none	Name of the company who is the registered keeper of the vehicle
address	Address	false	none	none

Address

{
  "line1": "DVLA Long View Rd",
  "line2": "Morriston",
  "line3": "Clase",
  "line4": "Swansea",
  "line5": "West Glamorgan",
  "postcode": "SA6 7JL"
}

Properties

Name	Type	Required	Restrictions	Description
line1	string	false	none	none
line2	string	false	none	none
line3	string	false	none	none
line4	string	false	none	none
line5	string	false	none	none
postcode	string	false	none	none

RegistrationNumber

"XYZ1"

Vehicle’s registration number.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	Pattern: ^(([A-Za-z]{1,2}[ ]?[0-9]{1,4})	([A-Za-z]{3}[ ]?[0-9]{1,3})

ChassisVin

"VF33BRFNC83846199"

Vehicle’s chassis identification number.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Vehicle’s chassis identification number.

ErrorResponse

{
  "errors": [
    {
      "status": 400,
      "code": "ENQ102",
      "detail": "Invalid format for field - vehicle registration number"
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
errors	[Error]	true	none	none

Error

{
  "status": 400,
  "code": "ENQ102",
  "detail": "Invalid format for field - vehicle registration number"
}

Properties

Name	Type	Required	Restrictions	Description
status	integer(int32)	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