Public Numbers API

These endpoints allow you to query publicly available phone numbers and read their incoming SMS messages.

Note: Access to these endpoints can be toggled by the administrators. If disabled, you will receive a 403 Forbidden (API_PUBLIC_DISABLED).

1. List Active Countries

Returns a list of all active countries that currently have active phone numbers available.

Endpoint: GET /countries

Example Request:

curl -X GET "https://receivefreesms.co.uk/developer/v1/countries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

2. List Public Numbers

Returns a paginated list of all active public phone numbers.

Endpoint: GET /numbers

Query Parameters:

• page (optional): The pagination page number.

Example Request:

curl -X GET "https://receivefreesms.co.uk/developer/v1/numbers?page=1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

3. Get Specific Number Details

Retrieve details and metadata for a specific public phone number.

Endpoint: GET /numbers/{slug}

Path Parameters:

• slug: The phone number (e.g., 1234567890).

Example Request:

curl -X GET "https://receivefreesms.co.uk/developer/v1/numbers/1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

4. Read Public Messages

Fetch the latest SMS messages received by a specific public number.

Endpoint: GET /numbers/{slug}/messages

Path Parameters:

• slug: The phone number.

Query Parameters:

• page (optional): For pagination.

Example Request:

curl -X GET "https://receivefreesms.co.uk/developer/v1/numbers/1234567890/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"