Driver and Vehicle Licensing Agency (DVLA) Renewal API

openapi: 3.2.0
info:
  title: Dvla Gov Uk Renewal API
  version: 1.0.2
  contact:
    name: DVLA Digital Services Support
    email: dvlaapiaccess@dvla.gov.uk
  termsOfService: https://developer-portal.driver-vehicle-licensing.api.gov.uk/apis/drivers/driving-licence-renewal-intermediary-api-description.html
  description: 'Operations tagged Renewal across 2 of this provider''s published API definitions: driving-licence-renewal-intermediary.json, dvla-gov-uk-driving-licence-renewal-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://uat.driver-vehicle-licensing.api.gov.uk/drivers-renewal
  description: Integration (Pre-Production) environment. Consumer integration testing only.
- url: https://driver-vehicle-licensing.api.gov.uk/drivers-renewal
  description: Production environment.
security:
- jwtAuth: []
  apiKeyAuth: []
tags:
- name: Renewal
  description: Renewal API
paths:
  /v1/drivers/renewal:
    post:
      tags:
      - Renewal
      operationId: POST-Drivers-Renewal
      summary: Submit a driving licence renewal application
      parameters:
      - $ref: '#/components/parameters/correlationId'
      - $ref: '#/components/parameters/originTimestamp'
      requestBody:
        description: Application being submitted
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DrivingLicenceRenewalRequest'
      responses:
        '202':
          description: Application accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DrivingLicenceRenewalResponse'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        '409':
          description: Conflict
          content:
            text/plain:
              schema:
                type: string
                example: A conflict occurred
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
    servers:
    - url: https://uat.driver-vehicle-licensing.api.gov.uk/drivers-renewal
      description: Integration (Pre-Production) environment. Consumer integration testing only.
    - url: https://driver-vehicle-licensing.api.gov.uk/drivers-renewal
      description: Production environment.
components:
  schemas:
    Photo:
      description: Photo image and qualify checks
      type: object
      example:
      - 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
      properties:
        photographImage:
          description: 'Driver photograph contentMediaType: "image/jpeg", "contentEncoding": "base64"'
          type: string
        photoOverride:
          type: boolean
          description: When the indicator is set to Y, the clerk has indicated a concern with photo compliance
        icaoCompliant:
          description: Flag to indicate whether or not the facial image is ICAO compliant
          type: boolean
        eyesOpen:
          description: Flag to indicate whether eyes are open
          type: boolean
        exposure:
          description: Flag to indicate whether exposure levels are correct
          type: boolean
        frontalView:
          description: Flag to indicate whether the image is a frontal view
          type: boolean
        greyscaleDensity:
          description: Flag to indicate whether the greyscale density is correct
          type: boolean
        uniformLighting:
          description: Flag to indicate whether lighting is uniform across face image
          type: boolean
        headWidth:
          description: Flag to indicate whether head width is within acceptable range
          type: boolean
        headLength:
          description: Flag to indicate whether head length is within acceptable range
          type: boolean
        widthHeightRatio:
          description: Flag to indicate whether face width to height ratio is correct
          type: boolean
        resolution:
          description: Flag to indicate whether image resolution is acceptable
          type: boolean
        verticalPosition:
          description: Flag to indicate whether vertical image position is acceptable
          type: boolean
        horizontallyCentered:
          description: Flag to indicate whether image is horizontally centered
          type: boolean
      required:
      - photographImage
    Language:
      type: string
      description: Specifies address language ISO code, CY for Welsh, EN for English
      example: CY
      enum:
      - EN
      - CY
    BadRequestError:
      type: object
      properties:
        status:
          type: string
          description: The error HTTP response status
          example: 400 BAD_REQUEST
        code:
          type: string
          description: An error code that relates to a specific error condition
          example: InvalidRequiredHeader
        title:
          type: string
          description: The error title
          example: Invalid Header
        detail:
          type: string
          description: Further detail about the error
          example: Recipient name field must not be empty.
      example:
        status: 400 BAD_REQUEST
        code: InvalidRequiredHeader
        title: Invalid Header
        detail: Recipient name field must not be empty.
    LicenceStatus:
      description: Licence Data
      type: object
      example:
        photocardSurrendered: true
        photocardIssueNumber: '12'
        lostMarker: false
        stolenMarker: false
        defacedMarker: false
        destroyedMarker: false
      properties:
        photocardSurrendered:
          description: Whether the photo card part of the licence has been surrendered to a third party
          type: boolean
        photocardIssueNumber:
          description: The licence photo card issue number
          type: string
          minLength: 1
          maxLength: 2
        lostMarker:
          description: A flag denoting whether the licence has been lost or not
          type: boolean
        stolenMarker:
          description: A flag denoting whether the licence has been stolen or not
          type: boolean
        defacedMarker:
          description: A flag denoting whether the licence has been defaced or not
          type: boolean
        destroyedMarker:
          description: A flag denoting whether the licence has been destroyed or not
          type: boolean
    OrganDonor:
      description: Organ Donor
      type: object
      example:
      - anyOrgans: true
      properties:
        anyOrgans:
          description: Any Organs
          type: boolean
        kidneys:
          description: Kidneys
          type: boolean
        liver:
          description: Liver
          type: boolean
        heart:
          description: Heart
          type: boolean
        cornea:
          description: Cornea
          type: boolean
        pancreas:
          description: Pancreas
          type: boolean
        lungs:
          description: lungs
          type: boolean
    TransactionID:
      description: Value used to uniquely identify a transaction within the client system, and to identify a request/response pair
      type: string
      minLength: 1
      maxLength: 36
    StructuredAddress:
      description: '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:

        poBoxNumber, organisationName, departmentName, subBuildingName,  buildingName, buildingNumber, dependentThoroughfareName,  thoroughfareName, doubleDependentLocality, dependentLocality

        '
      properties:
        poBoxNumber:
          type: string
          description: 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
          example: '21'
          maxLength: 6
        organisationName:
          type: string
          description: Name of the organisation registered at this address
          example: DVLA
          maxLength: 60
        departmentName:
          type: string
          description: Used to supplement Organisation Name to identify a department within the organisation
          example: ITS
          maxLength: 30
        subBuildingName:
          type: string
          description: 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
          example: Training Block
          maxLength: 30
        buildingName:
          type: string
          description: Name of residential or commercial premise
          example: RLDC
          maxLength: 50
        buildingNumber:
          type: string
          description: 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
          example: '1'
          maxLength: 4
        dependentThoroughfareName:
          type: string
          description: 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
          example: Bonllwyn
          maxLength: 80
        thoroughfareName:
          type: string
          description: 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
          example: High Street
          maxLength: 80
        doubleDependentLocality:
          type: string
          description: Used to distinguish between similar or same thoroughfares within a dependent locality, e.g. small villages
          example: Mumbles
          maxLength: 35
        dependentLocality:
          type: string
          description: Dependent locality areas may define an area within a post town
          example: Carmarthenshire
          maxLength: 35
        postTown:
          type: string
          description: 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
          example: Ammanford
          maxLength: 30
        postcode:
          type: string
          description: 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
          example: SA18 2EH
          maxLength: 8
        country:
          type: string
          description: Optionally specific address country, e.g 'Wales'
          example: Wales
          maxLength: 64
        language:
          $ref: '#/components/schemas/Language'
        dps:
          $ref: '#/components/schemas/DPS'
        uprn:
          type: string
          description: Unique Property Reference Number. Ordnance Survey unique alphanumeric identifier for every spatial address in Great Britain
          example: '100081043509'
          maxLength: 12
        udprn:
          type: string
          description: Unique Delivery Point Reference Number. An eight digit unique numeric code for delivery points on the PAF File as allocated by Royal Mail
          example: '25962203'
          maxLength: 8
      example:
        poBoxNumber: PO Box 21
        organisationName: BRITISH MONOMARKS LTD
        departmentName: VIRTUAL OFFICE
        subBuildingName: FLAT 2A
        buildingName: MONOMARK HOUSE
        buildingNumber: '27'
        dependentThoroughfareName: OLD GLOUCESTER STREET
        thoroughfareName: OLD GLOUCESTER STREET
        doubleDependentLocality: BLOOMSBURY
        dependentLocality: CAMDEN
        postTown: LONDON
        postcode: WC1N 3AX
        country: England
        language: EN
        dps: 1A
        uprn: '5138436'
        udprn: '26246290'
      required:
      - uprn
      - postTown
      - postcode
      - language
    InternalServerErrorResponse:
      type: object
      properties:
        errors:
          type: array
          description: Array of Error objects
          items:
            $ref: '#/components/schemas/InternalServerError'
      example:
        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'
    BfpoAddress:
      description: British Forces Post Office address, where BFPO Number is mandatory from the current list of operational BFPO numbers, and postcode is optional
      properties:
        line1:
          title: Line 1
          description: Free text, expected to be UNIT or REGIMENT.
          type: string
          minLength: 1
          maxLength: 45
          example: 12345678 LCPL B Jones
        line2:
          title: Line 2
          description: Free text, expected to be OPERATION.
          type: string
          minLength: 1
          maxLength: 45
          example: B Company
        line3:
          title: Line 3
          description: Free text, expected to be BARRACKS or CAMP or RAF STATION or NAVAL SHIP (if applicable).
          type: string
          minLength: 1
          maxLength: 45
          example: 1 Loamshire Regt
        line4:
          title: Line 4
          description: Free text
          type: string
          minLength: 1
          maxLength: 45
          example: HMS Dauntless
        bfpoNumber:
          title: BFPO Number
          type: integer
          minimum: 1
          maximum: 9999
          example: 5312
        postcode:
          type: string
          minLength: 1
          maxLength: 8
          example: SA18 2EH
      example:
        line1: 12345678 LCPL B Jones
        line2: B Company
        line3: 1 Loamshire Regt
        line4: HMS Dauntless
        bfpoNumber: 5432
        postcode: BF1 1FB
      required:
      - line1
      - bfpoNumber
    InternalServerError:
      type: object
      properties:
        status:
          type: string
          description: The error HTTP response status
          example: 500 INTERNAL_SERVER_ERROR
        code:
          type: string
          description: An error code that relates to a specific error condition
          example: '2'
        title:
          type: string
          description: Error title
          example: Unexpected Exception.
        detail:
          type: string
          description: Error detail
          example: 'An unexpected exception was raised by the service with Error Id: 16011497-35a9-4eef-885b-e5fe552693b8'
    DrivingLicenceRenewalResponse:
      description: Driving Licence Renewal Response component
      properties:
        transactionId:
          $ref: '#/components/schemas/TransactionID'
        dateTimeReceived:
          description: The date and time the request message was received by the DVLA service
          type: string
          format: date-time
      required:
      - transactionId
      - dateTimeReceived
      example:
        transactionId: 0922b8b5-a75b-4038-ae27-44bb36062af0
    UnstructuredAddress:
      description: Address manually entered by a user
      properties:
        line1:
          type: string
          minLength: 1
          maxLength: 45
          example: My Cottage
        line2:
          type: string
          minLength: 0
          maxLength: 45
          example: Apartment 2B
        line3:
          type: string
          minLength: 0
          maxLength: 45
          example: 1 My Street
        line4:
          type: string
          minLength: 0
          maxLength: 45
          example: Lingonberry
        postTown:
          type: string
          minLength: 0
          maxLength: 45
          example: London
        postcode:
          type: string
          minLength: 1
          maxLength: 8
          example: SA11 9ZZ
        language:
          $ref: '#/components/schemas/Language'
        dps:
          $ref: '#/components/schemas/DPS'
        pafIndicator:
          type: boolean
          description: Used by clients unable to supply a StructuredAddress or UnstructuredAddress with DPS. When the indicator is set to true, this indicates this is a valid address retrieved from Royal Mail Postcode Address File (PAF)
      example:
        line1: This is a line 1
        line2: VIRTUAL OFFICE
        line3: FLAT 99A
        line4: COPMANY HOUSE
        postTown: NEWTOWN
        postcode: WC1N 1ZZ
        language: EN
        pafIndicator: false
      required:
      - line1
      - postcode
      - language
    DPS:
      description: Royal Mail Delivery Point Suffix where matched to a PAF address. Uniquely identifies each address (Delivery Point) within a single postcode
      type: string
      maxLength: 2
      example: 9Z
    BadRequestErrorResponse:
      type: object
      properties:
        errors:
          type: array
          description: Array of Error objects
          items:
            $ref: '#/components/schemas/BadRequestError'
      example:
        errors:
        - status: 400 BAD_REQUEST
          code: NotEmpty
          title: standardParams.recipientName
          detail: Recipient name field must not be empty.
    Handler:
      description: Request meta data
      type: object
      properties:
        originatorId:
          description: Identifies the intermediary organisation supporting the application
          type: string
          maxLength: 256
        transactionId:
          $ref: '#/components/schemas/TransactionID'
        userId:
          description: This is the identifier for the Post Office clerk who carried out the enrolment in the branch
          type: string
          maxLength: 256
        branchId:
          description: Optionally identifies the branch at which the application took place
          type: string
          maxLength: 256
        terminalId:
          description: This is the terminal ID workstation that was used during enrolment
          type: string
          maxLength: 256
        localDateTime:
          description: The branch date and time stamp when the transaction commenced
          type: string
          format: date-time
      required:
      - transactionId
      example:
        originatorId: POL
        transactionId: 0922b8b5-a75b-4038-ae27-44bb36062af0
        userId: john-smith
        branchId: a123
        terminalId: '1581239'
        localDateTime: '2022-01-01T09:00:00Z'
    DrivingLicenceRenewalRequest:
      type: object
      description: request
      additionalProperties: false
      properties:
        handler:
          $ref: '#/components/schemas/Handler'
        drivingLicenceNumber:
          description: A UK driving licence number
          type: string
          maxLength: 16
          minLength: 16
          pattern: ^[A-Z9]{5}\d{6}[A-Z9]{2}[A-HJ-NPR-X2-9]{1}[A-Z]{2}$
        transactionType:
          description: "A field denoting the transaction type \n TYRR for a renewal reminder \n TYRPC for a photocard renewal"
          type: string
          enum:
          - TYRR
          - TYRPC
        applicationReferenceNumber:
          description: The application reference number as detailed in the barcode part of a D798 form
          type: string
          maxLength: 29
          example: '98269432242880068489880451164'
        feePaid:
          description: The total amount taken from the customer at the counter for this transaction in pence
          type: integer
          minimum: 0
          maximum: 999999
        investigationRequired:
          type: boolean
          description: When the indicator is set to Y, the clerk has decided that the DVLA should investigate the application
        dateOfBirth:
          type: string
          format: date
          description: The customer's date of birth
        daytimePhone:
          type: string
          minLength: 1
          maxLength: 30
          description: A daytime UK contact number
        photo:
          $ref: '#/components/schemas/Photo'
        signatureImage:
          description: 'Driver signature contentMediaType: "image/png", "contentEncoding": "base64"'
          type: string
        updateAddress:
          $ref: '#/components/schemas/UpdateAddress'
        licenceStatus:
          $ref: '#/components/schemas/LicenceStatus'
        twoDBarcode:
          description: 159 character representation of the contents of the Reminder barcode
          type: string
          maxLength: 159
        organDonor:
          $ref: '#/components/schemas/OrganDonor'
        photoCardFront:
          description: 'Photocard front - only required for Photocard (non Reminder) applications. contentMediaType: "image/jpeg", "contentEncoding": "base64"'
          type: string
        photoCardBack:
          description: 'Photocard back - only required for Photocard (non Reminder) applications. contentMediaType: "image/jpeg", "contentEncoding": "base64"'
          type: string
      required:
      - handler
      - transactionType
      - photo
      - feePaid
      - signatureImage
      example:
        handler:
          originatorId: POL
          transactionId: 0922b8b5-a75b-4038-ae27-44bb36062af0
          userId: john-smith
          branchId: a123
          terminalId: '1581239'
          localDateTime: '2022-01-01T09:00:00Z'
        drivingLicenceNumber: 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'
          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 2AB
            language: EN
        photoCardFront: BASE64JPEGSTRING
        photoCardBack: BASE64JPEGSTRING
        organDonor:
          anyOrgans: false
          kidneys: true
          liver: true
          heart: false
          cornea: false
          pancreas: true
          lungs: false
    UpdateAddress:
      description: 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:
        structuredAddress:
          $ref: '#/components/schemas/StructuredAddress'
        unstructuredAddress:
          $ref: '#/components/schemas/UnstructuredAddress'
        bfpoAddress:
          $ref: '#/components/schemas/BfpoAddress'
      example:
        structuredAddress:
          buildingName: MONOMARK HOUSE
          buildingNumber: '27'
          dependentThoroughfareName: OLD GLOUCESTER STREET
          thoroughfareName: OLD GLOUCESTER STREET
          doubleDependentLocality: BLOOMSBURY
          dependentLocality: CAMDEN
          postTown: LONDON
          postcode: WC1N 3AX
          country: England
          language: EN
          dps: 1A
          uprn: '5138436'
          udprn: '26246290'
  parameters:
    correlationId:
      name: X-Correlation-ID
      in: header
      description: Link log messages to a specific application request
      required: false
      schema:
        type: string
        example: b5d9b2bd-6e8f-4275-bdd3-c8086fe09c52
    originTimestamp:
      name: Origin-Timestamp
      in: header
      description: For informational / support purposes only, handy to identify network delays between source and destination.
      required: false
      schema:
        type: string
        example: '2022-01-01T09:00:00.000Z'
  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:
- driving-licence-renewal-intermediary.json
- dvla-gov-uk-driving-licence-renewal-openapi.yml