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.
​
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": "+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

Get started for freeTalk to us