Driver and Vehicle Licensing Agency (DVLA) Vehicle Keeper API

openapi: 3.2.0
info:
  title: Dvla Gov Uk Vehicle Keeper API
  version: 1.0.4
  contact:
    name: DVLA API Team
    email: kadoe.helpdesk@dvla.gov.uk
  description: 'Operations tagged Vehicle Keeper across 2 of this provider''s published API definitions: v1.0.4-kadoe.json, dvla-gov-uk-kadoe-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://driver-vehicle-licensing.api.gov.uk/kadoe
  description: Production environment
- url: https://uat.driver-vehicle-licensing.api.gov.uk/kadoe
  description: External testing (UAT) environment
security:
- jwtAuth: []
- apiKeyAuth: []
tags:
- name: Vehicle Keeper
paths:
  /v1/vehicle-keeper:
    post:
      summary: Retrieve Keeper at Date of Event for a vehicle
      operationId: getVehicleKeeper
      parameters: []
      requestBody:
        description: The vehicle's registration number or chassis number, the reason for the enquiry, and the event date time.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KadoeRequest'
            examples:
              RequestByVRN:
                value:
                  enquirerId: AA123
                  reasonCode: 00AC
                  registrationNumber: AA19AAA
                  eventDate: '2023-07-04'
                  referenceNumber: co6wz38alj0h
              RequestByVIN:
                value:
                  enquirerId: AA123
                  linkProviderId: LP146
                  reasonCode: 00BF
                  chassisVin: JH4KA8252NC002110
                  eventDate: '2023-07-04'
                  referenceNumber: co6wz38alj0h
        required: true
      responses:
        '200':
          description: Keeper details at date of event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KadoeResponse'
              examples:
                CitizenKeeperResponse:
                  value:
                    registrationNumber: XYZ1
                    make: PEUGEOT
                    model: 307 CC
                    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
                CompanyKeeperResponse:
                  value:
                    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':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                DetailsUnavailableError:
                  value:
                    errors:
                    - status: 404
                      code: ENV002
                      detail: Details unavailable response to follow
                NoInformationFoundError:
                  value:
                    errors:
                    - status: 404
                      code: ENV003
                      detail: No information found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                SystemError:
                  value:
                    errors:
                    - status: 500
                      code: ENV004
                      detail: System returned error
        '503':
          description: Service Unavailable
      tags:
      - Vehicle Keeper
    servers:
    - url: https://driver-vehicle-licensing.api.gov.uk/kadoe
      description: Production environment
    - url: https://uat.driver-vehicle-licensing.api.gov.uk/kadoe
      description: External testing (UAT) environment
components:
  schemas:
    ChassisVin:
      type: string
      description: Vehicle's chassis identification number.
      example: VF33BRFNC83846199
    KadoeRequest:
      type: object
      required:
      - enquirerId
      - reasonCode
      - eventDate
      - referenceNumber
      properties:
        enquirerId:
          type: string
          description: Identifier for the enquirer.
          example: AA001
        linkProviderId:
          type: string
          description: Identifier for the link provider, should there be one.
          example: A01
        reasonCode:
          type: string
          description: Code indicating the reason for the enquiry.
          example: 00ET
        registrationNumber:
          $ref: '#/components/schemas/RegistrationNumber'
        chassisVin:
          $ref: '#/components/schemas/ChassisVin'
        eventDate:
          type: string
          format: YYYY-MM-DD
          description: The date of event in format YYYY-MM-DD.
          example: '2006-05-26'
        referenceNumber:
          type: string
          description: Alpha-numeric reference provided by the enquirer.
          example: ABC123
    KadoeResponse:
      type: object
      properties:
        registrationNumber:
          $ref: '#/components/schemas/RegistrationNumber'
        chassisVin:
          $ref: '#/components/schemas/ChassisVin'
        make:
          type: string
          description: The make of the vehicle.
          example: PEUGEOT
        model:
          type: string
          description: The model of the vehicle.
          example: 307 CC
        fleetNumber:
          type: string
          description: The assigned fleet number of the vehicle.
          example: 4
        colour:
          type: string
          description: The vehicle's colour.
          example: Black
        secondaryColour:
          type: string
          description: Another colour present on the vehicle.
          example: Red
        keeper:
          $ref: '#/components/schemas/Keeper'
        message:
          type: string
          description: Information message for stolen, scrapped and exported vehicles.
          example: Vehicle stolen at date of event
        taxStatus:
          type: string
          description: The current tax status of the vehicle.
          example: Taxed
          enum:
          - Not Taxed for on Road Use
          - SORN
          - Untaxed
          - Taxed
        seatingCapacity:
          type: integer
          format: int32
          description: The seating capacity of the vehicle.
          example: 5
        bodyType:
          type: string
          description: The body type of the vehicle.
          example: Box Van
        taxClass:
          type: string
          description: The tax class of the vehicle.
          example: Disabled
    Address:
      type: object
      properties:
        line1:
          type: string
          example: DVLA Long View Rd
        line2:
          type: string
          example: Morriston
        line3:
          type: string
          example: Clase
        line4:
          type: string
          example: Swansea
        line5:
          type: string
          example: West Glamorgan
        postcode:
          type: string
          example: SA6 7JL
    Keeper:
      type: object
      properties:
        title:
          type: string
          description: Title of the person who is the registered keeper of the vehicle.
          example: MR
        firstNames:
          type: string
          description: First names of the person who is the registered keeper of the vehicle.
          example: Simon
        lastName:
          type: string
          description: Last name of the person who is the registered keeper of the vehicle.
          example: Fleet
        companyName:
          type: string
          description: Name of the company who is the registered keeper of the vehicle
          example: Microsoft
        address:
          $ref: '#/components/schemas/Address'
      additionalProperties: false
    Error:
      type: object
      properties:
        status:
          type: integer
          format: int32
          description: HTTP status code
          example: 400
        code:
          type: string
          description: DVLA reference code
          example: ENQ102
        detail:
          type: string
          description: A meaningful description of the error which has occurred
          example: Invalid format for field - vehicle registration number
    ErrorResponse:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    RegistrationNumber:
      type: string
      description: Vehicle's registration number.
      example: XYZ1
      pattern: ^(([A-Za-z]{1,2}[ ]?[0-9]{1,4})|([A-Za-z]{3}[ ]?[0-9]{1,3})|([0-9]{1,3}[ ]?[A-Za-z]{3})|([0-9]{1,4}[ ]?[A-Za-z]{1,2})|([A-Za-z]{3}[ ]?[0-9]{1,3}[ ]?[A-Za-z])|([A-Za-z][ ]?[0-9]{1,3}[ ]?[A-Za-z]{3})|([A-Za-z]{2}[ ]?[0-9]{2}[ ]?[A-Za-z]{3})|([A-Za-z]{3}[ ]?[0-9]{4}))$
  securitySchemes:
    jwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Valid JWT token issued as a result of authentication using the DVLA Authentication API
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key used to access the service
x-refined-from:
- v1.0.4-kadoe.json
- dvla-gov-uk-kadoe-openapi.yml