Skip to main content
GET
/
v2
/
notifications
/
{id}
Get Notification Status
curl --request GET \
  --url https://api.example.com/v2/notifications/{id}
{
  "id": "<string>",
  "reference": "<string>",
  "email_address": "<string>",
  "phone_number": "<string>",
  "line_1": "<string>",
  "line_2": "<string>",
  "line_3": "<string>",
  "line_4": "<string>",
  "line_5": "<string>",
  "line_6": "<string>",
  "postcode": "<string>",
  "type": "<string>",
  "status": "<string>",
  "template": {
    "template.id": "<string>",
    "template.version": 123,
    "template.uri": "<string>"
  },
  "body": "<string>",
  "subject": "<string>",
  "created_at": "<string>",
  "sent_at": "<string>",
  "completed_at": "<string>",
  "scheduled_for": "<string>",
  "estimated_delivery": "<string>",
  "postage": "<string>",
  "one_click_unsubscribe_url": "<string>",
  "cost_in_pounds": 123,
  "cost_details": {},
  "is_cost_data_ready": true
}

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.

Get the status and details of a notification by its ID.

​
Path Parameters

​
id
string
required
The UUID of the notification to retrieve.

​
Response

​
id
string
The unique identifier for this notification.
​
reference
string
The reference that was provided when the notification was created, or null.
​
email_address
string
The email address for email notifications, or null for other types.
​
phone_number
string
The phone number for SMS notifications, or null for other types.
​
line_1
string
First line of the postal address for letter notifications, or null for other types.
​
line_2
string
Second line of the postal address for letter notifications, or null for other types.
​
line_3
string
Third line of the postal address for letter notifications, or null for other types.
​
line_4
string
Fourth line of the postal address for letter notifications, or null for other types.
​
line_5
string
Fifth line of the postal address for letter notifications, or null for other types.
​
line_6
string
Sixth line of the postal address for letter notifications, or null for other types.
​
postcode
string
The postcode for letter notifications, or null for other types.
​
type
string
The notification type. One of: sms, email, letter.
​
status
string
The current status of the notification. Possible values:For SMS and Email:
  • created - The notification is being processed
  • sending - The notification is being sent
  • delivered - The notification was successfully delivered
  • sent - The notification was sent internationally (SMS only)
  • pending - The notification is pending
  • temporary-failure - The notification failed but may be retried
  • permanent-failure - The notification permanently failed
  • technical-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 validation
  • technical-failure - A technical error occurred
​
template
object
Information about the template used.
​
template.id
string
The UUID of the template.
​
template.version
integer
The version number of the template.
​
template.uri
string
The URI to retrieve the template.
​
body
string
The notification body content with placeholders filled in.
​
subject
string
The notification subject for emails and letters, or null for SMS.
​
created_at
string
ISO 8601 formatted datetime when the notification was created.
​
sent_at
string
ISO 8601 formatted datetime when the notification was sent, or null if not yet sent.
​
completed_at
string
ISO 8601 formatted datetime when the notification was completed (delivered or failed), or null if still in progress.
​
scheduled_for
string
ISO 8601 formatted datetime when the notification is scheduled to be sent, or null if not scheduled.
​
estimated_delivery
string
ISO 8601 formatted datetime of estimated delivery (letters only).
​
postage
string
The postage class for letter notifications. One of: first, second, economy, europe, rest-of-world.
​
one_click_unsubscribe_url
string
The one-click unsubscribe URL for email notifications, or null.
​
cost_in_pounds
number
The cost of sending this notification in pounds.
​
cost_details
object
Details about the cost calculation.
​
is_cost_data_ready
boolean
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": "user@example.gov.uk",
  "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"
    }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us