Get Notification Status

GET /v2/notifications/{id}

Get Notification Status

cURL

curl --request GET \
  --url https://api.example.com/v2/notifications/{id}

200

{
  "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
}

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": "[phone]",
  "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": "[e-mail]",
  "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"
    }
  ]
}