Skip to main content
GET
/
v2
/
received-text-messages
Get received text messages
curl --request GET \
  --url https://api.example.com/v2/received-text-messages
{
  "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.
​
links
object
required
Navigation links for pagination.

​
Example Request

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

# 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

Build docs developers (and LLMs) love

Get started for freeTalk to us