Skip to main content
GET
/
v2
/
notifications
List Notifications
curl --request GET \
  --url https://api.example.com/v2/notifications
{
  "notifications": [
    {}
  ],
  "links": {
    "links.current": "<string>",
    "links.next": "<string>"
  }
}
Get a paginated list of all notifications sent by your service.

Query Parameters

reference
string
Filter notifications by the reference you provided when sending. Returns all notifications with this reference.
status
array
Filter notifications by status. You can provide multiple status values. Possible values:For SMS and Email:
  • created
  • sending
  • sent
  • delivered
  • pending
  • failed
  • technical-failure
  • temporary-failure
  • permanent-failure
For Letters:
  • accepted - Letter accepted for printing
  • received - Letter received by postal service
  • cancelled
  • pending-virus-check
  • virus-scan-failed
  • validation-failed
  • technical-failure
  • returned-letter
template_type
array
Filter notifications by type. You can provide multiple types. Possible values: sms, email, letter.
older_than
string
A notification UUID. Returns the next page of notifications older than this notification. Use this for pagination.
include_jobs
string
Set to true or True to include notifications sent via CSV upload jobs. By default, only API-sent notifications are returned.

Response

notifications
array
An array of notification objects. Each notification has the same structure as returned by the Get Notification endpoint.
Pagination links.
The URL for the current page of results.
The URL for the next page of results, if there are more notifications to retrieve.

Example Request

curl -X GET "https://api.notifications.service.gov.uk/v2/notifications?status=delivered&template_type=email" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Request with Pagination

curl -X GET "https://api.notifications.service.gov.uk/v2/notifications?older_than=740e5834-3a29-46b4-9a6f-16142fde533a" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "notifications": [
    {
      "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
    },
    {
      "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
    }
  ],
  "links": {
    "current": "https://api.notifications.service.gov.uk/v2/notifications?status=delivered&template_type=email",
    "next": "https://api.notifications.service.gov.uk/v2/notifications?status=delivered&template_type=email&older_than=950e5834-3a29-46b4-9a6f-16142fde533b"
  }
}

Example Response (No More Results)

{
  "notifications": [],
  "links": {
    "current": "https://api.notifications.service.gov.uk/v2/notifications?older_than=abc12345-1234-5678-9abc-def012345678"
  }
}

Error Responses

400 Bad Request

Invalid status value
{
  "status_code": 400,
  "errors": [
    {
      "error": "ValidationError",
      "message": "status must be one of: created, sending, sent, delivered, pending, failed, technical-failure, temporary-failure, permanent-failure"
    }
  ]
}
Invalid template_type value
{
  "status_code": 400,
  "errors": [
    {
      "error": "ValidationError",
      "message": "template_type must be one of: sms, email, letter"
    }
  ]
}
Invalid older_than UUID
{
  "status_code": 400,
  "errors": [
    {
      "error": "ValidationError",
      "message": "older_than is not a valid UUID"
    }
  ]
}

Pagination

The API returns a maximum number of notifications per request (typically 250). To retrieve all notifications:
  1. Make an initial request without the older_than parameter
  2. Check if the response includes a links.next URL
  3. If present, extract the older_than value from the next URL
  4. Make another request with the older_than parameter
  5. Repeat until no links.next is present in the response

Notes

  • Notifications are returned in reverse chronological order (newest first)
  • The API retains notifications for 7 days
  • By default, only API-sent notifications are returned. Use include_jobs=true to include bulk upload notifications
  • Multiple status or template_type values can be provided by repeating the parameter: ?status=delivered&status=sent

Build docs developers (and LLMs) love