List Notifications

GET /v2/notifications

List Notifications

cURL

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

200

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

links · object

Pagination links.

links.current · string

The URL for the current page of results.

links.next · string

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": "[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
    },
    {
      "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
    }
  ],
  "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