Skip to main content
GET
/
v2
/
notifications
/
{id}
/
pdf
Get Letter PDF
curl --request GET \
  --url https://api.example.com/v2/notifications/{id}/pdf
Download the PDF for a letter notification. This endpoint is only available for letter notifications.

​
Path Parameters

​
id
string
required
The UUID of the letter notification.

​
Response

Returns the letter PDF file with Content-Type: application/pdf. The PDF contains the fully rendered letter including:
  • The recipient’s address
  • The letter content with all placeholders filled in
  • GOV.UK branding (if applicable)

​
Example Request

curl -X GET https://api.notifications.service.gov.uk/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a/pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output letter.pdf

​
Example Request (Save to File)

# Using curl
curl -X GET https://api.notifications.service.gov.uk/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a/pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o letter.pdf

# Using wget
wget --header="Authorization: Bearer YOUR_API_KEY" \
  https://api.notifications.service.gov.uk/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a/pdf \
  -O letter.pdf

​
Error Responses

​
400 Bad Request

Notification is not a letter 
{
  "status_code": 400,
  "errors": [
    {
      "error": "BadRequestError",
      "message": "Notification is not a letter"
    }
  ]
}
PDF not yet ready 
{
  "status_code": 400,
  "errors": [
    {
      "error": "PDFNotReadyError",
      "message": "PDF not available yet, try again later"
    }
  ]
}
Virus scan failed 
{
  "status_code": 400,
  "errors": [
    {
      "error": "BadRequestError",
      "message": "File did not pass the virus scan"
    }
  ]
}
PDF not available due to technical failure 
{
  "status_code": 400,
  "errors": [
    {
      "error": "BadRequestError",
      "message": "PDF not available for letters in status technical-failure"
    }
  ]
}
Invalid notification ID format 
{
  "status_code": 400,
  "errors": [
    {
      "error": "ValidationError",
      "message": "notification_id is not a valid UUID"
    }
  ]
}

​
404 Not Found

Notification not found 
{
  "status_code": 404,
  "errors": [
    {
      "error": "NoResultFound",
      "message": "No result found"
    }
  ]
}

​
PDF Availability

The PDF is typically available within a few seconds after sending a letter notification. However, for precompiled letters, the PDF may take longer to become available as it needs to:
  1. Pass virus scanning (pending-virus-check status)
  2. Be validated and processed
If you receive a PDFNotReadyError, wait a few seconds and try again.

​
Letter Statuses

You can only retrieve PDFs for letters in certain statuses: PDF Available:
  • accepted (created/sending)
  • received (delivered)
  • returned-letter
PDF Not Available:
  • pending-virus-check - Wait and retry
  • virus-scan-failed - Letter rejected, PDF not available
  • validation-failed - Letter rejected, PDF not available
  • technical-failure - Processing failed, PDF not available

​
Use Cases

  • Preview letters before they are sent
  • Archive copies of sent letters for record keeping
  • Verify letter content and formatting
  • Debug issues with letter generation

​
Notes

  • The PDF returned is the exact version that will be (or was) printed and posted
  • PDFs are retained for 7 days after creation
  • This endpoint is only available for letter notifications created via the API or admin interface
  • The PDF includes all GOV.UK Notify formatting and branding

Build docs developers (and LLMs) love

Get started for freeTalk to us