Skip to main content

DVLA Print Request Submission API v1.2.0

Manages the submission of print jobs which are fulfilled by the DVLA Output Service Group (OSG)

Click here to see this OpenAPI specification in JSON format.

Base URLs

Terms of service Email: Common Services Support

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-print-jobs

POST-Create-Print-Job

POST /v1/print/jobs

Submit a print job


Parameters

Name In Type Required Restrictions Description
X-Correlation-ID header string false none Link log messages to a specific application request
body body PrintJobRequest true none Print job to submit

Example Request

curl -X POST  -d '{
  "id": "cfce9e7b-1534-4c07-a66d-3cf9172f7640",
  "standardParams": {
    "jobType": "JOBTYPE ABC",
    "templateReference": "TEMPLATE 123",
    "businessIdentifier": "ABCDE123456",
    "recipientName": "Mr ABCD",
    "address": {
      "unstructuredAddress": {
        "line1": "This is a line 1",
        "line3": "VIRTUAL OFFICE",
        "line4": "FLAT 99A",
        "line5": "COMPANY HOUSE",
        "postcode": "WC1N 1ZZ",
        "dps": "1A"
      }
    },
    "handlingInstruction": {
      "line1": "This is a line 1",
      "line2": "This is a line 2",
      "line3": "This is a line 3",
      "line4": "This is a line 4"
    },
    "despatchMethod": "FIRST"
  },
  "customParams": [
    {
      "key": "Unladen Mass",
      "value": "36000 KG"
    },
    {
      "key": "vinOrChassisNumber",
      "value": "DVLA1234A1A123456"
    }
  ],
  "callbackParams": {
    "target": "https://example.com/your-callback",
    "authenticationHeader": "bearer qC3eUzFzWaeg9mGETlvvwejtlUwSPQaEIvCJ59vpoPShIm0HbhiTxbh0H2qwIPZS",
    "retryParams": {
      "enabled": true,
      "maxRetryWindow": 3600
    }
  }
}' https://uat.driver-vehicle-licensing.api.gov.uk/print-request/v1/print/jobs \
 -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'X-Correlation-ID: b5d9b2bd-6e8f-4275-bdd3-c8086fe09c52' -H 'Authorization: Bearer {access-token}'

Responses

Status Meaning Description Schema
202 Accepted Accepted, print job saved for later submission to OSG PrintJobCreationResponse
400 Bad Request Invalid parameters BadRequestErrorResponse
409 Conflict Print job id conflict ConflictErrorResponse
500 Internal Server Error Unexpected error InternalServerErrorResponse

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

Example Response

202 Response

{
  "id": "d1ac67e9-544d-44a6-b567-de0b02463c76"
}

409 Response

{
  "errors": [
    {
      "status": "409 CONFLICT",
      "code": "11",
      "title": "Print job cannot be created",
      "detail": "The supplied identifier conflicts with another print job. Please supply a unique identifier."
    }
  ]
}

v1-print-jobs-jobid

GET-Retrieve-Print-Job-Details

GET /v1/print/jobs/{jobId}

Retrieve print job by ID, including current status and job details


Parameters

Name In Type Required Restrictions Description
X-Correlation-ID header string false none Link log messages to a specific application request
jobId path string true none Identifier of the job to search for

Example Request

curl -X GET  https://uat.driver-vehicle-licensing.api.gov.uk/print-request/v1/print/jobs/{jobId} \
 -H 'Accept: application/json' -H 'X-Correlation-ID: b5d9b2bd-6e8f-4275-bdd3-c8086fe09c52' -H 'Authorization: Bearer {access-token}'

Responses

Status Meaning Description Schema
200 OK Returns the job matching the job identifer PrintJobResponse
404 Not Found Unknown print job NotFoundErrorResponse
500 Internal Server Error Unexpected error InternalServerErrorResponse

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

Example Response

200 Response

{
  "id": "d1ac67e9-544d-44a6-b567-de0b02463c76",
  "standardParams": {
    "jobType": "JOBTYPE ABC",
    "templateReference": "TEMPLATE 123",
    "businessIdentifier": "ABCDE123456",
    "recipientName": "Mr Dave Matthews",
    "address": {
      "structuredAddress": {
        "buildingNumber": "999",
        "thoroughfareName": "MY STREET LANE",
        "postTown": "SWANSEA",
        "postcode": "SA99 1ZZ",
        "country": "Wales",
        "language": "EN",
        "dps": "1A",
        "uprn": "123456789012",
        "udprn": "12345678"
      }
    },
    "handlingInstruction": {
      "line1": "This is a line 1",
      "line2": "This is a line 2",
      "line3": "This is a line 3",
      "line4": "This is a line 4"
    }
  },
  "customParams": [
    {
      "key": "Trailer Registration Number",
      "value": "D000001"
    }
  ],
  "callbackParams": {
    "target": "https://example.com/your-callback",
    "authenticationHeader": "bearer qC3eUzFzWaeg9mGETlvvwejtlUwSPQaEIvCJ59vpoPShIm0HbhiTxbh0H2qwIPZS",
    "retryParams": {
      "enabled": true,
      "maxRetryWindow": 3600
    }
  },
  "status": "PENDING",
  "comment": "This is a comment.",
  "createdDate": "2018-09-14T14:49:38.348Z",
  "updatedDate": "2018-09-14T15:01:01.001Z",
  "printableAddress": {
    "line1": "My House",
    "line2": "1 My Street",
    "line3": "My Locality",
    "line4": "Wales",
    "line5": "United Kingdom",
    "recipientLine1": "Mr. Longfirstname",
    "recipientLine2": "Longsurname",
    "postcode": "SA99 1ZZ",
    "dps": "9Z"
  }
}

404 Response

{
  "errors": [
    {
      "status": "404 NOT_FOUND",
      "code": "5",
      "title": "Print job not found",
      "detail": "No print job with id d1ac67e9-544d-44a6-b567-de0b02463c76 found."
    }
  ]
}

500 Response

{
  "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"
    }
  ]
}

DELETE-Print-Job

DELETE /v1/print/jobs/{jobId}

Delete given pending print job


Parameters

Name In Type Required Restrictions Description
X-Correlation-ID header string false none Link log messages to a specific application request
jobId path string true none Identifier of the job that is to be deleted

Example Request

curl -X DELETE  https://uat.driver-vehicle-licensing.api.gov.uk/print-request/v1/print/jobs/{jobId} \
 -H 'Accept: application/json' -H 'X-Correlation-ID: b5d9b2bd-6e8f-4275-bdd3-c8086fe09c52' -H 'Authorization: Bearer {access-token}'

Responses

Status Meaning Description Schema
204 No Content Deleted print job None
404 Not Found Unknown print job NotFoundErrorResponse
409 Conflict Print job is not in pending state, only pending print jobs can be deleted ConflictErrorResponse
500 Internal Server Error Unexpected error InternalServerErrorResponse

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

Example Response

404 Response

{
  "errors": [
    {
      "status": "404 NOT_FOUND",
      "code": "5",
      "title": "Print job not found",
      "detail": "No print job with ID d1ac67e9-544d-44a6-b567-de0b02463c76 found."
    }
  ]
}

409 Response

{
  "errors": [
    {
      "status": "409 CONFLICT",
      "code": "7",
      "title": "Print job cannot be cancelled.",
      "detail": "Print job with identifier d1ac67e9-544d-44a6-b567-de0b02463c76 cannot be deleted because it is in PRODUCTION status."
    }
  ]
}

500 Response

{
  "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"
    }
  ]
}

Schemas

Status

"DESPATCHED"

Defines the progress of the print job. The normal flow for a print job be PENDING -> PRODUCTION -> DESPATCHED. However, a job may end with a REJECTED status.

Properties

Name Type Required Restrictions Description
anonymous string false Enum: PENDING,PRODUCTION,DESPATCHED,REJECTED
 Defines the progress of the print job. The normal flow for a print job be PENDING -> PRODUCTION -> DESPATCHED. However, a job may end with a REJECTED status.

Enumerated Values

Property Value
anonymous PENDING
anonymous PRODUCTION
anonymous DESPATCHED
anonymous REJECTED

PrintJobResponse

{
  "id": "0922b8b5-a75b-4038-ae27-44bb36062af0",
  "standardParams": {
    "jobType": "JOBTYPE ABC",
    "templateReference": "TEMPLATE 123",
    "businessIdentifier": "ABCDE123456",
    "recipientName": "Mr Danny Boje",
    "address": {
      "structuredAddress": {
        "buildingNumber": "99",
        "thoroughfareName": "MY LANE",
        "postTown": "SWANSEA",
        "postcode": "SA99 1ZZ",
        "country": "Wales",
        "language": "EN",
        "dps": "1A",
        "uprn": "123456789012",
        "udprn": "12345678"
      }
    },
    "handlingInstruction": {
      "line1": "This is a line 1",
      "line2": "This is a line 2",
      "line3": "This is a line 3",
      "line4": "This is a line 4"
    },
    "despatchMethod": "FIRST"
  },
  "customParams": [
    {
      "key": "Unladen Mass",
      "value": "36000 KG"
    }
  ],
  "callbackParams": {
    "target": "https://example.com/your-callback",
    "authenticationHeader": "bearer qC3eUzFzWaeg9mGETlvvwejtlUwSPQaEIvCJ59vpoPShIm0HbhiTxbh0H2qwIPZS",
    "retryParams": {
      "enabled": true,
      "maxRetryWindow": 3600
    }
  },
  "status": "PENDING",
  "comment": null,
  "batchNumber": "80001",
  "fulfilmentJobId": "1000003001",
  "documentId": "65000",
  "printLocation": "MORRISTON",
  "serialNumber": "ZZ12345678",
  "despatchProperties": [
    {
      "key": "Chip Id",
      "value": "1234567890123456"
    }
  ],
  "createdDate": "2018-12-20T13:13:47.650Z",
  "updatedDate": "2019-01-25T11:14:15.198Z",
  "printableAddress": {
    "line1": "PO Box 999",
    "line2": "MY COMPANY",
    "line3": "123 COMPANY HOUSE",
    "line4": "MY OLD STREET",
    "line5": "MY TOWN",
    "recipientLine1": "MR ABCD",
    "recipientLine2": "",
    "postcode": "WC1N 1ZZ",
    "dps": "1A"
  }
}

Properties

Name Type Required Restrictions Description
id string false none Unique identifier used to identify a print job.
standardParams StandardParams true none The standard set of generic parameters for all print jobs. Supplied structured/unstructured address is wrapped in a parent “address” object
customParams [CustomParam] true Min items: 1
 Custom parameters specific to job type as per agreement with OSG
callbackParams CallbackParams false none Specific parameters for the print job status update callback
status Status false none Defines the progress of the print job. The normal flow for a print job be PENDING -> PRODUCTION -> DESPATCHED. However, a job may end with a REJECTED status.
comment string false none The most recent comment of this print job.
batchNumber string false none OSG print run number, a run contains fulfilment jobs.
fulfilmentJobId string false none OSG RPD system job batch number, a fulfilment job contains documents.
documentId string false none OSG RPD system document identifier
printLocation string false none Printing location
serialNumber string false none Content varies with print job type, e.g. card serial number or document serial number.
despatchProperties [DespatchProperty] false Min items: 1
 Despatch custom parameters from OSG
createdDate string(date-time) false none none
updatedDate string(date-time) false none none
printableAddress PrintableAddressResponse false none Address in a print-ready format suitable for use by OSG

PrintJobRequest

{
  "id": "cfce9e7b-1534-4c07-a66d-3cf9172f7640",
  "standardParams": {
    "jobType": "JOBTYPE ABC",
    "templateReference": "TEMPLATE 123",
    "businessIdentifier": "ABCDE123456",
    "recipientName": "Mr ABCD",
    "address": {
      "unstructuredAddress": {
        "line1": "This is a line 1",
        "line3": "VIRTUAL OFFICE",
        "line4": "FLAT 99A",
        "line5": "COMPANY HOUSE",
        "postcode": "WC1N 1ZZ",
        "dps": "1A"
      }
    },
    "handlingInstruction": {
      "line1": "This is a line 1",
      "line2": "This is a line 2",
      "line3": "This is a line 3",
      "line4": "This is a line 4"
    },
    "despatchMethod": "FIRST"
  },
  "customParams": [
    {
      "key": "Unladen Mass",
      "value": "36000 KG"
    },
    {
      "key": "vinOrChassisNumber",
      "value": "DVLA1234A1A123456"
    }
  ],
  "callbackParams": {
    "target": "https://example.com/your-callback",
    "authenticationHeader": "bearer qC3eUzFzWaeg9mGETlvvwejtlUwSPQaEIvCJ59vpoPShIm0HbhiTxbh0H2qwIPZS",
    "retryParams": {
      "enabled": true,
      "maxRetryWindow": 3600
    }
  }
}

Properties

Name Type Required Restrictions Description
id string false Pattern: [A-Za-z0-9_:.-]+
Max length: 255
 An optional identifier used to identify the provided print job. Where no identifier is supplied, the service will generate a unique identifier in the form of a UUID. Where the consumer supplies an identifier, it should be recorded at their end to ensure that requests can be referenced subsequently and should include a UUID to avoid the risk of a conflict with other jobs. It must not contain any personal information such as name or postal address. The Id may consist of any number of letters, digits ([0-9]), hyphens (“-”), underscores (“_”), colons (“:”), and periods (“.”).
standardParams StandardParams true none The standard set of generic parameters for all print jobs. Supplied structured/unstructured address is wrapped in a parent “address” object
customParams [CustomParam] true Min items: 1
 Custom parameters specific to job type as per agreement with OSG
callbackParams CallbackParams false none Specific parameters for the print job status update callback

StandardParams

{
  "jobType": "JOBTYPE ABC",
  "templateReference": "TEMPLATE 123",
  "businessIdentifier": "ABCDE123456",
  "recipientName": "Mr Abcd Efgh",
  "address": {
    "structuredAddress": {
      "buildingNumber": "99",
      "thoroughfareName": "MY LANE",
      "postTown": "SWANSEA",
      "postcode": "SA99 1ZZ",
      "country": "Wales",
      "language": "EN",
      "dps": "1A",
      "uprn": "123456789012",
      "udprn": "26246290"
    }
  },
  "handlingInstruction": {
    "line1": "This is a line 1",
    "line2": "This is a line 2",
    "line3": "This is a line 3"
  },
  "despatchMethod": "FIRST"
}

The standard set of generic parameters for all print jobs. Supplied structured/unstructured address is wrapped in a parent “address” object

Properties

Name Type Required Restrictions Description
jobType string true Min length: 1
Max length: 255
 Pre-agreed identifier for the type of print job submitted, describes the application the transaction relates too
templateReference string true Min length: 1
Max length: 255
 Reference to the pre-agreed print template e.g. MY TEMPLATE, ABCD
businessIdentifier string¦null false Pattern: [A-Za-z0-9_:.-]+
Min length: 1
Max length: 255
 Optional Business identifier to help identify the job for support purposes eg. a URN or customer reference that must only consist of any number of letters, digits ([0-9]), hyphens (“-”), underscores (“_”), colons (“:”), and periods (“.”).
recipientName string true Min length: 1
Max length: 255
 Full name of postal recipient including any title if relevant.
Note that this field is mapped to two separate lines for the printable
address (fit for envelope window). The maximum length for each line
is 45 characters.

Where the recipient name is greater than 45 characters in length, the first line
is wrapped onto the second line using the following rules:

- If the first line contains at least one space prior to the 45th character, the nearest space
prior to the 45th character is removed and anything following the space is wrapped onto the
second line.

For example:

Recipient name:
This is a long name and it will show an example of how wrapping can occur.

Would become:
Line 1 - This is a long name and it will show an
Line 2 - example of how wrapping can occur.

- If the first line contains at least one hyphen prior to the 45th character, the nearest hyphen
prior to the 45th character is left on the first line, and anything following the hyphen is wrapped to
the next line.

For example:

Recipient name:
This-is-a-long-name-and-it-will-show-an-example-of-how-wrapping-can-occur.

Would become:
Line 1 - This-is-a-long-name-and-it-will-show-an-
Line 2 - example-of-how-wrapping-can-occur.

- If neither a space or hyphen are present prior to the 45th character, then
a hard wrap will result.

Recipient name:
Line 1 - Thisisalongnameanditwillshowanexampleofhowwra
Line 2 - ppingcanoccur.

Any characters beyond the length of 90 are omitted.
address Address true none At least one and only one of the structured or unstructured addresses must be provided.
handlingInstruction HandlingInstruction false none A Handling Instruction is passed to inform OSG where to send the printed items to once completed at OSG.
despatchMethod string false Enum: FIRST,INTERNAL,INTERNATIONAL_EU,INTERNATIONAL_ROW,SPECIAL
 Postage class despatch method for specific job types so that they can instruct OSG to send certain jobs out as eg. 1st class as opposed to the standard method.

Enumerated Values

Property Value
despatchMethod FIRST
despatchMethod INTERNAL
despatchMethod INTERNATIONAL_EU
despatchMethod INTERNATIONAL_ROW
despatchMethod SPECIAL

Address

{
  "structuredAddress": {
    "poBoxNumber": "PO Box 999",
    "organisationName": "BRITISH COMPANY LTD",
    "departmentName": "VIRTUAL OFFICE",
    "subBuildingName": "FLAT 99A",
    "buildingName": "COMPANY HOUSE",
    "buildingNumber": "99",
    "dependentThoroughfareName": "OLD GLOUCESTER STREET",
    "thoroughfareName": "OLD GLOUCESTER ROAD",
    "doubleDependentLocality": "BLOOMSBURY",
    "dependentLocality": "CAMDEN",
    "postTown": "LONDON",
    "postcode": "WC1N 1ZZ",
    "country": "England",
    "language": "EN",
    "dps": "1A",
    "uprn": "513843691536",
    "udprn": "26246290"
  }
}

One and only one of the structured, unstructured, or international addresses must be provided. This is the address to be used for external dispatch and could be the customer residential address on record or a separate correspondence address. This will be converted into a standard printable address format for output in the address window. A print job may require an additional set of addresses to be used within the print output that differs from the printable dispatch address, either by format or by delivery point. These are often in specific formats so are not catered for in standard parameters and can be added as custom parameters as necessary. For bulk mail handling, mail providers require that the majority (90% at the time of writing) of dispatch addresses are supplied as validated Structured addresses with corresponding DPS and mailsort code information.

Properties

Name Type Required Restrictions Description
structuredAddress StructuredAddress false none Address containing PAF fields for a single address, including DPS which if provided open the opportunity for postal cost savings.
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 OSG for
delivery to a recipient:
departmentName, organisationName, poBoxNumber,
buildingNumber, subBuildingName, buildingName, thoroughfareName,
doubleDependentLocality, dependentThoroughfareName,
dependentLocality, postTown
unstructuredAddress UnstructuredAddress false none Address manually entered by a user.
bfpoAddress BfpoAddress false none none
internationalAddress InternationalAddress false none An International Address for external consumers, field examples are not provided due to range of possible values

StructuredAddress

{
  "poBoxNumber": "PO Box 999",
  "organisationName": "BRITISH COMPANY LTD",
  "departmentName": "VIRTUAL OFFICE",
  "subBuildingName": "FLAT 99A",
  "buildingName": "COMPANY HOUSE",
  "buildingNumber": "99",
  "dependentThoroughfareName": "OLD GLOUCESTER STREET",
  "thoroughfareName": "OLD GLOUCESTER ROAD",
  "doubleDependentLocality": "BLOOMSBURY",
  "dependentLocality": "CAMDEN",
  "postTown": "LONDON",
  "postcode": "WC1N 1ZZ",
  "country": "England",
  "language": "EN",
  "dps": "1A",
  "uprn": "513843691536",
  "udprn": "26246290"
}

*Address containing PAF fields for a single address, including DPS which if provided open the opportunity for postal cost savings. 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 OSG for delivery to a recipient: departmentName, organisationName, poBoxNumber, buildingNumber, subBuildingName, buildingName, thoroughfareName, doubleDependentLocality, dependentThoroughfareName, dependentLocality, postTown *

Properties

Name Type Required Restrictions Description
poBoxNumber string¦null false none none
organisationName string¦null false none none
departmentName string¦null false none none
subBuildingName string¦null false none none
buildingName string¦null false none none
buildingNumber string¦null false none none
dependentThoroughfareName string¦null false none none
thoroughfareName string¦null false none none
doubleDependentLocality string¦null false none none
dependentLocality string¦null false none none
postTown string¦null false none none
postcode string¦null false none none
country string¦null false none none
language string¦null false none none
dps string¦null false none none
uprn string¦null false none none
udprn string¦null false none none

UnstructuredAddress

{
  "line1": "This is a line 1",
  "line2": null,
  "line3": "VIRTUAL OFFICE",
  "line4": "FLAT 99A",
  "line5": "COPMANY HOUSE",
  "postcode": "WC1N 1ZZ",
  "dps": "1A"
}

Address manually entered by a user.

Properties

Name Type Required Restrictions Description
line1 string true Min length: 1
Max length: 45
 none
line2 string false Max length: 45
 none
line3 string false Max length: 45
 none
line4 string false Max length: 45
 none
line5 string false Max length: 45
 none
postcode string true Min length: 1
Max length: 10
 none
dps string false Max length: 2
 none

BfpoAddress

{
  "line1": "12345678 LCPL B Jones",
  "line2": "B Company",
  "line3": "1 Loamshire Regt",
  "line4": "HMS Dauntless",
  "bfpoNumber": 5432,
  "postcode": "BF1 1FB",
  "language": "EN",
  "country": "England"
}

Properties

Name Type Required Restrictions Description
line1 string true Min length: 1
Max length: 45
 Free text, expected to be SERVICE NUMBER, RANK and NAME.
line2 string¦null false Min length: 1
Max length: 45
 Free text, expected to be UNIT or REGIMENT.
line3 string¦null false Min length: 1
Max length: 45
 Free text, expected to be OPERATION.
line4 string¦null false Min length: 1
Max length: 45
 Free text, expected to be BARRACKS or CAMP or RAF STATION or NAVAL SHIP (if applicable).
bfpoNumber integer true Minimum: 1
Maximum: 9999
 none
postcode string false Min length: 1
Max length: 10
 none
language string¦null false none none
country string¦null false none none

InternationalAddress

{
  "line1": "78 HARVEY ROAD",
  "line2": "VIRTUAL OFFICE  FLAT 99A",
  "line3": "COMPANY HOUSE WC1N 1ZZ",
  "country": "Canada"
}

An International Address for external consumers, field examples are not provided due to range of possible values

Properties

Name Type Required Restrictions Description
line1 string true Min length: 1
Max length: 45
 none
line2 string false Max length: 45
 none
line3 string false Max length: 45
 none
line4 string false Max length: 45
 none
line5 string false Max length: 45
 none
country string true Min length: 1
Max length: 256
 none

HandlingInstruction

{
  "handlingInstruction": {
    "line1": "This is a line 1",
    "line2": "This is a line 2",
    "line3": "This is a line 3",
    "line4": "This is a line 4",
    "line5": "This is a line 5",
    "line6": "This is a line 6",
    "line7": "This is a line 7"
  }
}

An internal Handling Instruction may be used in exceptional cases where the print output is required to have a specific handling instruction, typically for routing to an internal address. The Handling Instruction is printed in front of the dispatch address and output within the address window. Handling Instructions are only used by specific templates. The template (templateReference) will indicate whether a Handling Instruction is supported. Where a Handling Instruction does apply to a template, at least one line must be supplied (line1). Supplying a Handling Instruction in a Print Request for a template that does not support a Handling Instruction will be ignored.

Properties

Name Type Required Restrictions Description
line1 string true Min length: 1
Max length: 45
 none
line2 string false Max length: 45
 none
line3 string false Max length: 45
 none
line4 string false Max length: 45
 none
line5 string false Max length: 45
 none
line6 string false Max length: 45
 none
line7 string false Max length: 45
 none

CustomParam

{
  "key": "Unladen Mass",
  "value": "36000 KG"
}

Specific set of parameters for print job based on job type

Properties

Name Type Required Restrictions Description
key string true Min length: 1
 Provided keys must be unique. Duplication of keys will result in an error response.
value string true Min length: 1
 none

CallbackParams

{
  "target": "https://example.com/your-callback",
  "authenticationHeader": "bearer qC3eUzFzWaeg9mGETlvvwejtlUwSPQaEIvCJ59vpoPShIm0HbhiTxbh0H2qwIPZS",
  "retryParams": {
    "enabled": true,
    "maxRetryWindow": 10800
  }
}

Specific parameters for the print job status update callback

Properties

Name Type Required Restrictions Description
target string true Min length: 11
 The URL that callback requests will be sent to
authenticationHeader string¦null false Min length: 1
 String provided in the Authentication header for the callback request
retryParams CallbackRetryParams false none Callback retry parameters

CallbackRetryParams

{
  "enabled": true,
  "maxRetryWindow": 10800
}

Configuration block for Webhook retries

Properties

Name Type Required Restrictions Description
enabled boolean¦null false none Enable retries for failed webhook requests
maxRetryWindow integer¦null false Minimum: 30
Maximum: 86400
 The window we will retry to send failed webhooks for (in seconds), using exponential backoff

DespatchProperty

{
  "key": "Chip Id",
  "value": "1234567890123456"
}

A property (key-value pair) for a despatched print job.

Properties

Name Type Required Restrictions Description
key string true Min length: 1
Max length: 50
 Must Be Unique
value string true Min length: 1
Max length: 255
 none

PrintableAddressResponse

{
  "line1": "PO Box 21",
  "line2": "VIRTUAL OFFICE BRITISH LTD",
  "line3": "27 COMPANY HOUSE OLD GLOUCESTER STREET",
  "line4": "OLD GLOUCESTER STREET",
  "line5": "BLOOMSBURY CAMDEN",
  "recipientLine1": "Mr Abcd Efgh",
  "recipientLine2": "",
  "postcode": "WC1N 1ZZ",
  "dps": "1A"
}

Address in a print-ready format suitable for use by OSG

Properties

Name Type Required Restrictions Description
line1 string false Min length: 1
Max length: 45
 none
line2 string false Max length: 45
 none
line3 string false Max length: 45
 none
line4 string false Max length: 45
 none
line5 string false Max length: 45
 none
postcode string false Max length: 8
 none
dps string¦null false none none
recipientLine1 string false Min length: 1
Max length: 45
 none
recipientLine2 string false Max length: 45
 none

PrintJobCreationResponse

{
  "id": "d1ac67e9-544d-44a6-b567-de0b02463c76"
}

Properties

Name Type Required Restrictions Description
id string true none Unique identifier used to identify a print job.

BadRequestErrorResponse

{
  "errors": [
    {
      "status": "400 BAD_REQUEST",
      "code": "NotEmpty",
      "title": "standardParams.recipientName",
      "detail": "Recipient name field must not be empty."
    }
  ]
}

Properties

Name Type Required Restrictions Description
errors [BadRequestError] false none Array of Error objects

InternalServerErrorResponse

{
  "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"
    }
  ]
}

Properties

Name Type Required Restrictions Description
errors [InternalServerError] false none Array of Error objects

NotFoundErrorResponse

{
  "errors": [
    {
      "status": "404 NOT_FOUND",
      "code": "5",
      "title": "Print job not found",
      "detail": "No print job with id 34efffb2-22f8-4c63-b52b-055a33624902 found."
    }
  ]
}

Properties

Name Type Required Restrictions Description
errors [NotFoundError] false none Array of Error objects

ConflictErrorResponse

{
  "errors": [
    {
      "status": "409 CONFLICT",
      "code": "7",
      "title": "Print job cannot be cancelled",
      "detail": "Print job with identifier 0922b8b5-a75b-4038-ae27-44bb36062af0 cannot be cancelled because it is in PRODUCTION status."
    }
  ]
}

Properties

Name Type Required Restrictions Description
errors [ConflictError] false none Array of Error objects

BadRequestError

{
  "status": "400 BAD_REQUEST",
  "code": "InvalidRequiredHeader",
  "title": "Invalid Header",
  "detail": "Recipient name field must not be empty."
}

Properties

Name Type Required Restrictions Description
status string false none The error HTTP response status
code string false none An error code that relates to a specific error condition
title string false none The error title
detail string false none Further detail about the error

InternalServerError

{
  "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"
}

Properties

Name Type Required Restrictions Description
status string false none The error HTTP response status
code string false none An error code that relates to a specific error condition
title string false none Error title
detail string false none Error detail

NotFoundError

{
  "status": "404 NOT_FOUND",
  "code": "5",
  "title": "Item not found",
  "detail": "No print job with id 34efffb2-22f8-4c63-b52b-055a33624902 found."
}

Properties

Name Type Required Restrictions Description
status string false none The error HTTP response status
code string false none An error code that relates to a specific error condition
title string false none Error title
detail string false none Error detail

ConflictError

{
  "status": "409 CONFLICT",
  "code": "7",
  "title": "Print job cannot be cancelled",
  "detail": "Print job with identifier 0922b8b5-a75b-4038-ae27-44bb36062af0 cannot be cancelled because it is in PRODUCTION status."
}

Properties

Name Type Required Restrictions Description
status number false none The error HTTP response status
code number false none An error code that relates to a specific error condition
title string false none Error title
detail string false none Error detail