Get the status and details of a notification by its ID.
Path Parameters
The UUID of the notification to retrieve.
Response
The unique identifier for this notification.
The reference that was provided when the notification was created, or null.
The email address for email notifications, or null for other types.
The phone number for SMS notifications, or null for other types.
First line of the postal address for letter notifications, or null for other types.
Second line of the postal address for letter notifications, or null for other types.
Third line of the postal address for letter notifications, or null for other types.
Fourth line of the postal address for letter notifications, or null for other types.
Fifth line of the postal address for letter notifications, or null for other types.
Sixth line of the postal address for letter notifications, or null for other types.
The postcode for letter notifications, or null for other types.
The notification type. One of: sms, email, letter.
The current status of the notification. Possible values:For SMS and Email:
created - The notification is being processedsending - The notification is being sentdelivered - The notification was successfully deliveredsent - The notification was sent internationally (SMS only)pending - The notification is pendingtemporary-failure - The notification failed but may be retriedpermanent-failure - The notification permanently failedtechnical-failure - A technical error occurred
For Letters:
accepted - The letter has been accepted for printing (maps to created or sending)received - The letter has been received by the postal service (maps to delivered)pending-virus-check - The letter is being scanned for viruses (precompiled only)virus-scan-failed - The letter failed virus scanning (precompiled only)validation-failed - The letter failed validationtechnical-failure - A technical error occurred
Information about the template used.The UUID of the template.
The version number of the template.
The URI to retrieve the template.
The notification body content with placeholders filled in.
The notification subject for emails and letters, or null for SMS.
ISO 8601 formatted datetime when the notification was created.
ISO 8601 formatted datetime when the notification was sent, or null if not yet sent.
ISO 8601 formatted datetime when the notification was completed (delivered or failed), or null if still in progress.
ISO 8601 formatted datetime when the notification is scheduled to be sent, or null if not scheduled.
ISO 8601 formatted datetime of estimated delivery (letters only).
The postage class for letter notifications. One of: first, second, economy, europe, rest-of-world.
one_click_unsubscribe_url
The one-click unsubscribe URL for email notifications, or null.
The cost of sending this notification in pounds.
Details about the cost calculation.
Whether the cost data is ready and accurate.
Example Request
curl -X GET https://api.notifications.service.gov.uk/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a \
-H "Authorization: Bearer YOUR_API_KEY"
Example Response (SMS)
{
"id": "740e5834-3a29-46b4-9a6f-16142fde533a",
"reference": "appointment-reminder-123",
"email_address": null,
"phone_number": "+447700900123",
"line_1": null,
"line_2": null,
"line_3": null,
"line_4": null,
"line_5": null,
"line_6": null,
"postcode": null,
"type": "sms",
"status": "delivered",
"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"
},
"body": "Hello John Smith, your appointment is on 12 March 2024.",
"subject": null,
"created_at": "2024-03-03T10:30:00.000000Z",
"sent_at": "2024-03-03T10:30:02.000000Z",
"completed_at": "2024-03-03T10:30:05.000000Z",
"scheduled_for": null,
"postage": null,
"one_click_unsubscribe_url": null,
"cost_in_pounds": 0.016,
"cost_details": {},
"is_cost_data_ready": true
}
Example Response (Email)
{
"id": "950e5834-3a29-46b4-9a6f-16142fde533b",
"reference": "email-confirmation-456",
"email_address": "[email protected]",
"phone_number": null,
"line_1": null,
"line_2": null,
"line_3": null,
"line_4": null,
"line_5": null,
"line_6": null,
"postcode": null,
"type": "email",
"status": "delivered",
"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"
},
"body": "Dear Jane Doe, your reference number is REF-12345.",
"subject": "Confirmation for Jane Doe",
"created_at": "2024-03-03T11:15:00.000000Z",
"sent_at": "2024-03-03T11:15:01.000000Z",
"completed_at": "2024-03-03T11:15:10.000000Z",
"scheduled_for": null,
"postage": null,
"one_click_unsubscribe_url": null,
"cost_in_pounds": 0.00,
"cost_details": {},
"is_cost_data_ready": true
}
Example Response (Letter)
{
"id": "a60e5834-3a29-46b4-9a6f-16142fde533c",
"reference": "letter-ref-789",
"email_address": null,
"phone_number": null,
"line_1": "The Occupier",
"line_2": "123 High Street",
"line_3": "London",
"line_4": null,
"line_5": null,
"line_6": null,
"postcode": "SW1A 1AA",
"type": "letter",
"status": "accepted",
"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"
},
"body": "Dear John Smith,\n\nYour reference number is ABC123.",
"subject": "Your reference number",
"created_at": "2024-03-03T09:00:00.000000Z",
"sent_at": null,
"completed_at": null,
"scheduled_for": null,
"estimated_delivery": "2024-03-06T16:00:00.000000Z",
"postage": "second",
"one_click_unsubscribe_url": null,
"cost_in_pounds": 0.69,
"cost_details": {},
"is_cost_data_ready": true
}
Error Responses
400 Bad Request
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"
}
]
}