Get received text messages

Retrieve a list of text messages received by your service

GET /v2/received-text-messages

Get received text messages

cURL

curl --request GET \
  --url https://api.example.com/v2/received-text-messages

200

{
  "200": {},
  "400": {},
  "401": {},
  "403": {},
  "received_text_messages": [
    {
      "id": {},
      "user_number": "<string>",
      "notify_number": "<string>",
      "content": "<string>",
      "created_at": {},
      "service_id": {}
    }
  ],
  "links": {
    "current": "<string>",
    "next": "<string>"
  }
}

This endpoint retrieves all text messages received by your service. Messages are returned in descending order by creation date (newest first).

Authentication

This endpoint requires authentication using an API key with the following header:

Authorization: Bearer {api_key}

Query Parameters

older_than · string (UUID)

Use this parameter to get the next page of results. Set to the id of the last message from the previous response. This returns messages created before the specified message.

If omitted, returns the most recent messages.

Response

received_text_messages · array

Array of received text message objects. Empty array if no messages are found.

Show Message object properties

id · string (UUID) · required

Unique identifier for the received text message.

user_number · string · required

The phone number that sent the message to your service.

notify_number · string · required

Your service’s phone number that received the message.

content · string · required

The content of the received text message.

created_at · string (ISO 8601) · required

The date and time the message was received, in ISO 8601 format.

Example: 2024-03-15T14:30:00.000000Z

service_id · string (UUID) · required

The unique identifier of your service.

links · object · required

Navigation links for pagination.

Show Links properties

current · string · required

URL for the current page of results.

next · string

URL for the next page of results. This field is only present when there are more results available.

The URL includes the older_than parameter set to the id of the last message in the current response.

Example Request

cURL

curl -X GET "https://api.notifications.service.gov.uk/v2/received-text-messages" \
  -H "Authorization: Bearer {api_key}"

Example Response

{
  "received_text_messages": [
    {
      "id": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
      "user_number": "447700900111",
      "notify_number": "447700900000",
      "content": "Hello, I'd like to enquire about my application",
      "created_at": "2024-03-15T14:30:00.000000Z",
      "service_id": "12345678-90ab-cdef-1234-567890abcdef"
    },
    {
      "id": "b2c3d4e5-f678-90a1-b2c3-d4e5f6789012",
      "user_number": "447700900222",
      "notify_number": "447700900000",
      "content": "Thank you for your help",
      "created_at": "2024-03-15T14:25:00.000000Z",
      "service_id": "12345678-90ab-cdef-1234-567890abcdef"
    }
  ],
  "links": {
    "current": "https://api.notifications.service.gov.uk/v2/received-text-messages",
    "next": "https://api.notifications.service.gov.uk/v2/received-text-messages?older_than=b2c3d4e5-f678-90a1-b2c3-d4e5f6789012"
  }
}

Pagination

This endpoint uses cursor-based pagination. The default page size is controlled by the API_PAGE_SIZE configuration setting.

To retrieve the next page of results:

1. Get the id of the last message in the current response
2. Make a new request with the older_than parameter set to that id
3. Continue until the next link is not present in the response

Example: Paginating Through Results

cURL

# Get first page
curl -X GET "https://api.notifications.service.gov.uk/v2/received-text-messages" \
  -H "Authorization: Bearer {api_key}"

# Get next page using the id from the last message
curl -X GET "https://api.notifications.service.gov.uk/v2/received-text-messages?older_than=b2c3d4e5-f678-90a1-b2c3-d4e5f6789012" \
  -H "Authorization: Bearer {api_key}"

Response Codes

200 · Success

The request was successful. Returns a list of received text messages (may be empty).

400 · Bad Request

Invalid request parameters. For example, if you provide an invalid older_than UUID or include unexpected query parameters.

{
  "status_code": 400,
  "errors": [
    {
      "error": "ValidationError",
      "message": "Additional properties are not allowed (invalid_param was unexpected)"
    }
  ]
}

401 · Unauthorized

Missing or invalid API key.

403 · Forbidden

The API key does not have permission to access this service’s received messages.

Notes

• Messages are stored for 7 days by default, unless your service has a custom data retention policy
• To receive text messages, your service must have an inbound SMS number configured
• The content of received messages is encrypted at rest and decrypted when retrieved through the API
• Messages are returned in descending order by created_at (newest first)
• An empty array is returned if there are no messages or if you’ve paginated past all available messages

Related Endpoints

• Send a text message
• Get a single message status