Work with number data.

01 / API reference

One feed for number availability

The numbers status feed describes the free public and members-only inventory listed by the site. Use it to build a number directory, filter by country or app, or monitor which numbers are active.

02 / Quickstart

Make your first request

Ask the site administration for an API token. After access is approved, replace YOUR_API_TOKEN in the example or set RECEIVE_SMS_API_TOKEN on your server.

curl --get 'https://receive-smss.live/api/public/numbers' \
  --header 'X-API-Key: YOUR_API_TOKEN' \
  --header 'Accept: application/json' \
  --data-urlencode 'status=active' \
  --data-urlencode 'access=public' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'offset=0'

// Server-side JavaScript (Node.js). Keep the token on your server.
const token = process.env.RECEIVE_SMS_API_TOKEN;
if (!token) throw new Error('Set RECEIVE_SMS_API_TOKEN first');

const url = new URL('https://receive-smss.live/api/public/numbers');
url.search = new URLSearchParams({
  status: 'active', access: 'public', limit: '20', offset: '0'
}).toString();

const response = await fetch(url, {
  headers: { 'X-API-Key': token, Accept: 'application/json' },
  signal: AbortSignal.timeout(10000)
});

if (!response.ok) {
  throw new Error('API request failed: HTTP ' + response.status);
}

const data = await response.json();
console.log(data.numbers);

# Python 3 standard library. Keep the token on your server.
import json
import os
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

query = urlencode({
    'status': 'active', 'access': 'public', 'limit': 20, 'offset': 0
})
request = Request(
    'https://receive-smss.live/api/public/numbers?' + query,
    headers={
        'X-API-Key': os.environ['RECEIVE_SMS_API_TOKEN'],
        'Accept': 'application/json',
    },
)

try:
    with urlopen(request, timeout=10) as response:
        data = json.load(response)
    print(data['numbers'])
except HTTPError as error:
    raise RuntimeError('API request failed: HTTP ' + str(error.code)) from error
except URLError as error:
    raise RuntimeError('Could not reach the API') from error

Examples are for reference. This page does not send API requests or generate tokens.

03 / Authentication

Authenticate with your API token

Send the token issued by the site administration in the X-API-Key header. An API token is separate from your website password and login session.

X-API-Key: YOUR_API_TOKEN
Accept: application/json

Clients that use a Bearer header can send the same token this way. This is an API key, not an OAuth access token. X-API-Key takes precedence if both headers are sent.

Authorization: Bearer YOUR_API_TOKEN

04 / List numbers

List numbers and their status

Returns the matching number metadata, filtered totals and pagination information. All query parameters are optional. Combine filters to narrow the results.

Unknown status or access values fall back to all. Numeric values are clamped to their supported range. A country or app with no matches returns an empty numbers array.

05 / Response format

Read the response

The example below uses fictional data. It illustrates the response structure, not the live inventory or an available phone number.

{
  "success": true,
  "generatedAt": "2026-10-29T12:00:00.000Z",
  "filters": {
    "status": "active",
    "access": "public",
    "country": null,
    "app": null
  },
  "counts": {
    "total": 1,
    "active": 1,
    "inactive": 0,
    "returned": 1
  },
  "paging": {
    "limit": 20,
    "offset": 0,
    "hasMore": false
  },
  "numbers": [
    {
      "number": "+12025550123",
      "status": "active",
      "access": "public",
      "type": "mobile",
      "country": {
        "code": "US",
        "slug": "usa",
        "name": "United States",
        "nameAr": "الولايات المتحدة",
        "phoneCode": "+1"
      },
      "region": null,
      "apps": [
        "whatsapp"
      ],
      "receivedCount": 12,
      "lastMessageAt": "2026-10-29T11:58:00.000Z",
      "url": "https://receive-smss.live/sms/usa/12025550123",
      "addedAt": "2026-10-01T09:00:00.000Z",
      "updatedAt": "2026-10-29T11:58:00.000Z"
    }
  ]
}

06 / Pagination

Read the next page

Start with offset=0. If paging.hasMore is true, increase offset by counts.returned and keep the same filters. Stop when hasMore is false. The inventory can change between requests, so deduplicate by number when collecting multiple pages.

// Keep the same filters and page size on every request.
// After each successful response:
if (data.paging.hasMore) {
  const nextOffset = data.paging.offset + data.counts.returned;
  // Use nextOffset as the offset parameter for the next page.
}

07 / Rate limits

Stay within the request limit

The limit is shared by requests from the same IP address. A 429 response includes Retry-After: 60. Wait before retrying and avoid parallel polling loops.

Successful responses can be cached for 30 seconds, with a stale-while-revalidate window of 60 seconds. Allow for this delay when showing availability. Repeated requests will not make incoming SMS arrive sooner.

08 / Errors

Handle errors by HTTP status

{
  "success": false,
  "error": "Invalid API key."
}

09 / Integration practices

Build a predictable integration

10 / FAQ

Before you integrate