SMS verification API reference

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 one exception is GET /v1/wallet/balance, which accepts an API key so you can check funds before buying. 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 to receive your verification 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", "code_count": 1, … }

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

[
  {
    "id": "…",
    "code": "552310",
    "received_at": "2026-06-17T22:21:07Z"
  },
  {
    "id": "…",
    "code": "482910",
    "received_at": "2026-06-17T22:18:44Z"
  }
]

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"

Purchases are paid from your prepaid wallet. Check your balance before buying to avoid a 402. Deposits and ledger history are dashboard-only.

curl https://api.fetchsms.com/v1/wallet/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

{ "balance_cents": 12345 }

Amounts are always integer cents. A purchase that costs more than your balance returns 402 with a detail message, and nothing is charged.

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).