The Fetch SMS API lets you rent real US non-VOIP phone numbers and receive SMS verification codes programmatically. It is a JSON REST API over HTTPS.

The fastest path: list services, create a verification, then poll it until the code arrives.

# 1. Pick a service id
curl https://api.fetchsms.com/v1/services

# 2. Rent a number for it
curl https://api.fetchsms.com/v1/verifications \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": 4}'

# 3. Poll until "code" is populated (most codes arrive in seconds)
curl https://api.fetchsms.com/v1/verifications/<id> \
  -H "Authorization: Bearer YOUR_API_KEY"

Authenticate programmatic verification and rental requests with an API key in the Authorization header as a bearer token. Create and rotate keys on the API page of your dashboard. Keys are shown only once, so store them securely.

Authorization: Bearer YOUR_API_KEY

Dashboard, account, wallet, support, admin, and API-key management routes require a dashboard session token and reject API keys. The public catalog endpoints (GET /v1/services and GET /v1/services/quote) do not require a key.

Errors use standard HTTP status codes and a JSON body with a single field:

{ "detail": "Telegram is out of stock for short-term verifications" }

Rate limit: 100 requests/second per API key. Poll for codes at a sane interval (every 2–5 seconds is plenty).

Fetch SMS has two separate products — short-term and long-term are priced and sold independently:

List the catalog with GET /v1/services. Anywhere the API takes a service, pass the stable numeric id. Slugs like telegram are also accepted for compatibility.

curl https://api.fetchsms.com/v1/services

[
  {
    "id": 2,
    "slug": "whatsapp",
    "name": "WhatsApp",
    "price_cents": 140,
    "long_prices": {},
    "short_available": 200,
    "long_available": 100
  }
]

curl "https://api.fetchsms.com/v1/services/area-codes?mode=short&service=2"

["212", "332", "415", "628", "917"]

Short-term verifications are priced per service — each costs that service's verification price (price_cents).

Long-term rentals are a single flat-priced product: one dedicated number that works for any service, billed per term. The price does not depend on which services you use the number for.

A custom area code adds a flat $0.10 surcharge to either product.

curl "https://api.fetchsms.com/v1/services/quote?service=4&mode=short&custom_area_code=true"

{
  "service": "telegram",
  "mode": "short",
  "days": null,
  "base_daily_cents": 70,
  "discount_pct": 0,
  "per_day_cents": null,
  "surcharge_cents": 10,
  "total_cents": 80
}

curl "https://api.fetchsms.com/v1/services/quote?service=1&mode=long&days=30"

{
  "service": "unlimited-services",
  "mode": "long",
  "days": 30,
  "base_daily_cents": 300,
  "discount_pct": 87,
  "per_day_cents": 40,
  "surcharge_cents": 0,
  "total_cents": 1200
}

A verification reserves a number for a single code inside a fixed 15-minute window. The wallet is debited up front; if the window closes (or you cancel) before any code arrives, the charge is automatically refunded — you are only charged on receipt.

Verifications are per service: the code is released only when the inbound SMS matches the service you purchased — a code for a different service is not shown and the verification keeps waiting. The response and webhook carry the code only, never the message body.

curl https://api.fetchsms.com/v1/verifications \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": 4, "area_code": "332"}'

{
  "id": "9f3e1c2a-…",
  "ref": "v_8R3p2K",
  "service": "telegram",
  "service_name": "Telegram",
  "number": "(332) 555-0184",
  "code": null,
  "status": "waiting",
  "cost_cents": 70,
  "created_at": "2026-06-17T22:14:05Z",
  "expires_at": "2026-06-17T22:29:05Z"
}

curl https://api.fetchsms.com/v1/verifications/9f3e1c2a-… \
  -H "Authorization: Bearer YOUR_API_KEY"

{ "id": "9f3e1c2a-…", "status": "received", "code": "482910", … }

curl "https://api.fetchsms.com/v1/verifications?tab=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST https://api.fetchsms.com/v1/verifications/9f3e1c2a-…/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

A rental gives you an exclusive number for 1–365 days that works for any service and receives unlimited codes for the whole term — a single flat-priced product (priced per term, not per service). A rental that ends without ever receiving a code is refunded.

curl https://api.fetchsms.com/v1/rentals \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": 1, "days": 30}'

{
  "id": "1a2b3c4d-…",
  "ref": "r_K9m2Lp",
  "service": "unlimited-services",
  "service_name": "Unlimited Services",
  "number": "(415) 555-0142",
  "duration_days": 30,
  "last_code": null,
  "status": "waiting",
  "cost_cents": 1200,
  "created_at": "2026-06-17T22:14:05Z",
  "expires_at": "2026-07-17T22:14:05Z"
}

curl https://api.fetchsms.com/v1/rentals/1a2b3c4d-… \
  -H "Authorization: Bearer YOUR_API_KEY"

curl https://api.fetchsms.com/v1/rentals/1a2b3c4d-…/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

[
  {
    "id": "…",
    "sender": "WhatsApp",
    "body": "Your WhatsApp code: 821-193",
    "code": "821-193",
    "received_at": "2026-06-17T22:31:10Z"
  }
]

curl "https://api.fetchsms.com/v1/rentals?tab=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST https://api.fetchsms.com/v1/rentals/1a2b3c4d-…/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

Purchases are paid from your prepaid wallet balance. API-key requests can spend from that balance through verification and rental purchases, but wallet balance, deposits, and ledger history are dashboard-only and do not accept API keys.

Instead of polling, register an endpoint to receive events the moment they happen. Add and manage endpoints on the API page. Each delivery is a POST with a JSON body.

Delivery headers:

Example sms.received payload:

{
  "event": "sms.received",
  "data": {
    "verification_id": "9f3e1c2a-…",
    "ref": "v_8R3p2K",
    "number": "(332) 555-0184",
    "sender": "Telegram",
    "code": "482910",
    "detected_service": "Telegram",
    "received_at": "2026-06-17T22:15:30Z"
  },
  "created_at": "2026-06-17T22:15:30Z"
}

Short-term verification events carry the code only — never the message body. A long-term rental event carries rental_id (instead of verification_id) and includes the full body. A rental.expired payload carries rental_id, ref, and number.

Verify the signature before trusting a delivery:

import crypto from 'node:crypto'

function verify(rawBody, signature, endpointSecret) {
  const expected = crypto
    .createHmac('sha256', endpointSecret)
    .update(rawBody)
    .digest('hex')
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
}

Every short-term verification service with its stable numeric id, slug, and price — pass the id to POST /v1/verifications. Live per-service stock is returned by GET /v1/services (the short_available field). The long-term unlimited-services rental product is not a short-term service and is excluded here (see Pricing).