curl --request POST \
--url https://api.example.com/v2/notifications/letter \
--header 'Content-Type: application/json' \
--data '
{
"template_id": "<string>",
"personalisation": {},
"reference": "<string>",
"content": "<string>",
"postage": "<string>"
}
'{
"id": "<string>",
"reference": "<string>",
"content": {
"content.body": "<string>",
"content.subject": "<string>"
},
"uri": "<string>",
"template": {
"template.id": "<string>",
"template.version": 123,
"template.uri": "<string>"
},
"scheduled_for": null,
"postage": "<string>"
}curl --request POST \
--url https://api.example.com/v2/notifications/letter \
--header 'Content-Type: application/json' \
--data '
{
"template_id": "<string>",
"personalisation": {},
"reference": "<string>",
"content": "<string>",
"postage": "<string>"
}
'{
"id": "<string>",
"reference": "<string>",
"content": {
"content.body": "<string>",
"content.subject": "<string>"
},
"uri": "<string>",
"template": {
"template.id": "<string>",
"template.version": 123,
"template.uri": "<string>"
},
"scheduled_for": null,
"postage": "<string>"
}Send a letter notification. You can send either a templated letter or a precompiled PDF.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/alphagov/notifications-api/llms.txt
Use this file to discover all available pages before exploring further.
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)first, second, economy, europe, rest-of-world.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"
}'
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"
}'
{
"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
}
{
"id": "740e5834-3a29-46b4-9a6f-16142fde533a",
"reference": "precompiled-letter-123",
"postage": "second"
}
{
"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"
}
]
}
{
"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"
}
]
}
{
"status_code": 404,
"errors": [
{
"error": "NoResultFound",
"message": "No result found"
}
]
}
{
"status_code": 429,
"errors": [
{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type LIVE of 3000 requests per 60 seconds"
}
]
}