Skip to main content

Print Request API Documentation

NOTE: This is a DRAFT for discussion, review and early integration with initial consumer(s).

Introduction

The Print Request API Service allows government departments to submit bulk print jobs to DVLA print services for processing.

Interactions with the Print Request API is via a REST Interface over HTTPS. In all cases, JSON is used for request and response data. The functional specification of this format is detailed in the OpenAPI 3.0 documentation below:

For more details visit the OpenAPI specification page.
You can also view the OpenAPI specification in JSON format.

The Print Request API implements the DVLA Secure API Pattern so requires DVLA Authentication API use to supply JWT, as well as an assigned API Key

Before submitting a print request, a corresponding print template must be agreed between the requesting service and DVLA Output Services Group (OSG). Specific required print data is supplied in custom parameters that must be specified and configured with OSG in advance. Further guidance is available from DVLA OSG Department.

PDF & Image Files

PDFs may be included in a Print Request specification as a base 64 encoded string; in this case the PDF should conform to the OSG Common PDF Specifications. Similarly, images may be sent as a base 64 encoded string provided they conform to the OSG Common Image Specifications.

API Services

Create Print Job

Creates a print job to be processed, optionally supplying print job ID

Get Print Job by ID

Get print job for the given job ID. Response data limited to include status, jobType, templateReference, comment (in case of rejection by OSG) and created/updated dates.

Delete Print Job by ID

Delete the print job for a specified Print Job ID

Usage Plans and Throttling Limits

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.

Royal Mail Address construction

In order to improve our ability to deliver mail to the end user and enable bulk mail discounts, supply of validated structuredAddress recipient addresses are preferable to unstructuredAddress. Access to a corresponding address postcode lookup service could be considered to help lookup addresses in this format if these fields are not already held by consumers.

Overview

Starting from v1.2.0 of the DVLA Print Request Submission API, you can provide a callback URL to receive updates on the status of your print job from Print Hub.

Status Updates

If a callback URL is configured Print Hub will send a POST request to this URL when the job status changes to either DESPATCHED or REJECTED. The callback endpoint should return HTTP 204.

Callback Retries

If retries are configured for the job, Print Hub will retry the callback using an exponential backoff mechanism if it receives any of the following HTTP response codes:

  • HTTP 429
  • HTTP 500
  • HTTP 503
  • HTTP 504

Body of Callback Request

{
  "id": "string", // message id, e.g. cfce9e7b-1534-4c07-a66d-3cf9172f7640
  "source": "string", // e.g. dvla:resource:osl:print:print-hub:5.6.0
  "specVersion": "string",
  "type": "string", // e.g. uk.gov.dvla.osl.print.v1.printjob-webhook-status  
  "time": "DateTime",
  "dataContentType": "application/json",
  "dataSchema": "print/v1/printjob-webhook-status",
  "data": {
    "despatchProperties": [
      {
        "key": "totalSheets",
        "value": "3" // effectively page count
      },
      {
        "key": "postageClass",
        "value": "1ST" // one of 1ST, 2ND, INTERNATIONAL
      },
      {
        "key": "mailingProduct",
        "value": "MM UNSORTED" // one of UNCODED, MM UNSORTED, UNSORTED, MM, INT EU, INT ROW
      },
      {
        "key": "Print Date",
        "value": "2024-08-01T09:15:14.456Z"
      },
      {
          "key": "KeyName",
          "value": "Value"
      },
      {
          "key": "AnotherKeyName",
          "value": " Another Value"
      }
    ],
    "jobId": "string", // identifier used to identify the provided print job
    "jobType": "string",
    "jobStatus": "Enum", // one of https://developer-portal.driver-vehicle-licensing.api.gov.uk/apis/printhub-request-api/printhub-request-api.html#enumerated-values
    "templateReference": "string",
    "transitionDate": "string" // e.g. 2024-08-01T11:15:30.456Z - DateTime job transitioned to new status
  },
  "metadata": {
    "handler": {
      "urn": "string" // e.g. dvla:resource:osl:print:print-hub:5.6.0"
    },
    "origin": {
      "urn": "string" // e.g. dvla:resource:osg:dev:printhub:1.0.1"
    },
    "correlationId": "string" // e.g. b5d9b2bd-6e8f-4275-bdd3-c8086fe09c52
  }
}

The ‘Get Print Job by ID’ endpoint may be used to determine status on an adhoc basis until a means to push status updates is available.

Release Notes

v1.0.4

  • Updated to include International and BFPO Address types

v1.0.0

  • Initial draft external version based on the PrintHub API