Send a letter notification. You can send either a templated letter or a precompiled PDF.
Templated Letter Request Body
The UUID of the letter template to use.
Key-value pairs to fill in placeholders in the template. For letters, this must include address fields:
address_line_1 (required)address_line_2 (optional)address_line_3 (optional)address_line_4 (optional)address_line_5 (optional)address_line_6 (optional)postcode (optional)
A unique identifier for this notification that you can use to identify it later. Maximum 1,000 characters.
Precompiled Letter Request Body
A unique identifier for this notification.
Base64 encoded PDF file content. The PDF must be a valid letter format.
The postage class for the letter. Valid values: first, second, economy, europe, rest-of-world.
Response
Templated Letter Response
The unique identifier for this notification.
The reference you provided, or null if you did not provide one.
The content of the letter notification.The letter body with placeholders filled in.
The letter subject with placeholders filled in.
The URI to retrieve this notification.
Information about the template used.The UUID of the template.
The version number of the template.
The URI to retrieve the template.
Letters cannot be scheduled. This will always be null.
Precompiled Letter Response
The unique identifier for this notification.
The reference you provided.
The postage class for the letter.
Example Templated Letter Request
curl -X POST https://api.notifications.service.gov.uk/v2/notifications/letter \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
"personalisation": {
"address_line_1": "The Occupier",
"address_line_2": "123 High Street",
"address_line_3": "London",
"postcode": "SW1A 1AA",
"name": "John Smith",
"reference_number": "ABC123"
},
"reference": "letter-ref-789"
}'
Example Precompiled Letter Request
curl -X POST https://api.notifications.service.gov.uk/v2/notifications/letter \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reference": "precompiled-letter-123",
"content": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKL01lZGlhQm94IFswIDAgNTk1IDg0Ml0KPj4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovUmVzb3VyY2VzIDw8Ci9Gb250IDw8Ci9GMSA0IDAgUgo+Pgo+PgovQ29udGVudHMgNSAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUxCi9CYXNlRm9udCAvVGltZXMtUm9tYW4KPj4KZW5kb2JqCjUgMCBvYmoKPDwKL0xlbmd0aCAzNAo+PgpzdHJlYW0KQlQKL0YxIDI0IFRmCjEwMCA3MDAgVGQKKEhlbGxvIFdvcmxkKSBUagpFVAplbmRzdHJlYW0KZW5kb2JqCnhyZWYKMCA2CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxNSAwMDAwMCBuIAowMDAwMDAwMDY2IDAwMDAwIG4gCjAwMDAwMDAxMzMgMDAwMDAgbiAKMDAwMDAwMDI0NSAwMDAwMCBuIAowMDAwMDAwMzMzIDAwMDAwIG4gCnRyYWlsZXIKPDwKL1NpemUgNgovUm9vdCAxIDAgUgo+PgpzdGFydHhyZWYKNDE3CiUlRU9G",
"postage": "second"
}'
Example Templated Letter Response
{
"id": "740e5834-3a29-46b4-9a6f-16142fde533a",
"reference": "letter-ref-789",
"content": {
"subject": "Your reference number",
"body": "Dear John Smith,\n\nYour reference number is ABC123."
},
"uri": "https://api.notifications.service.gov.uk/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
"template": {
"id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
"version": 1,
"uri": "https://api.notifications.service.gov.uk/services/8b3aa916-e138-4d4b-8c96-da8b6ddfe9a2/templates/f33517ff-2a88-4f6e-b855-c550268ce08a"
},
"scheduled_for": null
}
Example Precompiled Letter Response
{
"id": "740e5834-3a29-46b4-9a6f-16142fde533a",
"reference": "precompiled-letter-123",
"postage": "second"
}
Error Responses
400 Bad Request
Missing required field
{
"status_code": 400,
"errors": [
{
"error": "ValidationError",
"message": "personalisation is a required property"
}
]
}
{
"status_code": 400,
"errors": [
{
"error": "BadRequestError",
"message": "Cannot decode letter content (invalid base64 encoding)"
}
]
}
{
"status_code": 400,
"errors": [
{
"error": "ValidationError",
"message": "address_line_1 is a required property in personalisation"
}
]
}
403 Forbidden
Service does not have permission to send letters
{
"status_code": 403,
"errors": [
{
"error": "BadRequestError",
"message": "Service is not allowed to send letter"
}
]
}
{
"status_code": 403,
"errors": [
{
"error": "BadRequestError",
"message": "Cannot send letters with a team api key"
}
]
}
{
"status_code": 403,
"errors": [
{
"error": "BadRequestError",
"message": "Cannot send letters when service is in trial mode"
}
]
}
404 Not Found
Template not found
{
"status_code": 404,
"errors": [
{
"error": "NoResultFound",
"message": "No result found"
}
]
}
429 Too Many Requests
Rate limit exceeded
{
"status_code": 429,
"errors": [
{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type LIVE of 3000 requests per 60 seconds"
}
]
}