Skip to main content

Keeper At Date Of Event (KADOE) API Guide

The KADOE API is currently not available. Further information will be provided to users in due course.

The KADOE API OpenAPI 3.0 technical specification can be found here
It is also available in JSON format

Introduction

The DVLA Keeper At Date Of Event API is a RESTful service that provides details of a vehicle and its keeper at a point in time. The response data is provided in JSON format.

Request

To consume the API, make an HTTP POST request to the following URL:

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

Authentication

The Access to Driver Data API implements the DVLA secure API pattern so requires usage of the DVLA Authentication API to supply a JSON Web Token (JWT).

Body

To request data for a VRN

{
  "registrationNumber": "XYZ1",
  "enquirerId": "IT321",
  "reasonCode": "00EV",
  "eventDate": "2023-04-01",
  "referenceNumber": "ABC123"
}

Do not include any spaces or non-alphanumeric characters in the VRN.

To request data for a VIN

{
  "chassisVin": "VF33BRFNC83846199",
  "enquirerId": "IT321",
  "linkProviderId": "0024",
  "reasonCode": "00EV",
  "eventDate": "2023-04-01",
  "referenceNumber": "ABC123"
}

Do not include any spaces or non-alphanumeric characters in the VIN.

Example

Using curl, a request can be made as follows:

curl -L -X POST 'https://driver-vehicle-licensing.api.gov.uk/kadoe/v1/vehicle-keeper' \
-H "Authorization: REPLACE WITH YOUR JWT" \
-H "x-dvla-organisation: YOUR ENQUIRER ID" \
-H 'Content-Type: application/json' \
-d '{
  "registrationNumber": "XYZ1",
  "enquirerId": "IT321",
  "reasonCode": "00EV",
  "eventDate": "2023-04-01",
  "referenceNumber": "ABC123"
}'

Where a link provider is sending a request on behalf of a client organisation, the link provider ID is used for x-dvla-header.

OWASP security guidelines dictate that sensitive information should not be included in URLs. This reduces the risk of sensitive information being unnecessarily recorded in Web Server logs. The vehicle registration number / vehicle identification number is deemed sensitive information in accordance with the Information Commissioner’s Office (ICO), so is passed in the body as a POST request.

Response

A successful request should return a JSON response like the one below:

{
  "registrationNumber": "XYZ1",
  "make": "Honda",
  "model": "CR-V",
  "taxStatus": "Untaxed",
  "keeper": {
    "title": "MISS",
    "firstNames": "NPBPG OYOT",
    "lastName": "TCAEUCJ",
    "address": {
      "line1": "78 A TEST DATA DO NOT DELIVER",
      "line2": "Shameka Ports",
      "line3": "New Lissette",
      "line4": "Cornwall",
      "line5": "United Kingdom",
       "postcode": "DY92 6JB"
    }
}
}

Test Environment

Optionally, access to a test environment can be provided which will allow you to test your integration using several predefined vehicle registration numbers (VRN) and vehicle identification numbers (VIN), including error responses. This will allow you to reliably create scenarios with specific responses from the KADOE API.

A full list of test VRNs can be found here.


Request

To call the test API, make an HTTP POST request in the same manner as normal but to the following URL:

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

Remember to include the authentication headers.

Response

If you make a request to the test API with a predetermined VRN that will return an error code, like ‘ENV011’, your response should look something like this:

{
  "errors": [
    {
      "status": "404",
      "code": "ENV011",
      "detail": "Vehicle notified as scrapped"
    }
  ]
}

Usage Plans and Throttling Limits

Please note - only one API key can be issued per customer/company. Multiple API keys should not be requested as these are not permitted.

We have introduced limits on API usage rates in terms of requests per second. This applies to both individual clients and collective usage for all clients.

  1. A client’s limit is set based on the usage plan that the client is subscribed to
  2. As clients access the API at the same time, there is an overall limit on how many requests are allowed per second in order to protect the service

These two scenarios will return an HTTP status code of 429 as specified in the common errors section.

Support

Please direct any technical support queries to kadoemigrationteam@dvla.gov.uk and include KADOE API technical query in the subject line.