Build phone verification into your own product.

Getting access

The Reseller API is not self-serve. Every reseller is reviewed and approved by us before an API key is issued — this keeps supply predictable for the resellers who are already trading on it.

To apply, fill in the application form — it takes about two minutes. If it's a fit, we'll set up your reseller account, fund it with your first deposit, and send you an API key.

Authentication

Every request carries your API key as a bearer token. Keys look like coda_live_….

Authorization: Bearer coda_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Your key identifies your reseller account. Orders are billed to that account's balance — there is no account or user field in any request body, so a key can only ever spend its own balance and read its own orders.

Base URL

https://api.codasms.com

All endpoints are under /v1. Requests and responses are JSON. All amounts are integer US cents — never floats. A response always carries an ok boolean; check it before reading anything else.

Rate limits

60 requests per minute, per key. Exceeding it returns 429 with reason: "rate_limited" and a retryAfterSeconds field. Back off and retry — the window is rolling, not fixed.

If you need a higher limit for a specific integration, ask us. It's a per-key setting.

Balance

Your current balance. Check it before a batch of orders — an order against an empty balance fails with 402 and costs you a round trip.

# request
curl https://api.codasms.com/v1/balance \
  -H "Authorization: Bearer coda_live_..."

# response
{
  "ok": true,
  "balance_cents": 15000,
  "balance_usd": 150.00,
  "currency": "USD"
}

balance_cents is authoritative. balance_usd is a convenience float for display — never use it for arithmetic.

Services & countries

The live catalog: what's buyable, where, at what price, with current stock.

Filters

Unfiltered, this returns the entire catalog — around 500KB. If you want one cell, ask for one cell.

# request
curl "https://api.codasms.com/v1/services?service=tg&country=6" \
  -H "Authorization: Bearer coda_live_..."

# response
{
  "ok": true,
  "currency": "USD",
  "filters": { "service": "tg", "country": "6" },
  "counts":  { "services": 1, "countries": 1 },
  "services":  [ { "code": "tg", "name": "Telegram", "from_cents": 61, "stock": 2349045 } ],
  "countries": [ { "code": "6", "name": "Indonesia", "iso": "ID", "flag": "🇮🇩" } ],
  "matrix": {
    "6": { "tg": { "standard_cents": 61, "priority_cents": 92, "count": 2349045 } }
  },
  "generated_at": "2026-07-17T07:20:36.529Z",
  "stale": false
}

The matrix is the part that matters. It's keyed matrix[country][service] and holds the real price for that exact combination. The from_cents on a service is its cheapest price anywhere — a headline figure, not a quote.

The catalog refreshes about every 5 minutes and responses carry Cache-Control: max-age=300. stale: true means you're seeing a slightly old snapshot; the prices are still what we'd charge, so it's safe to use.

Countries

A lightweight list of the countries you can buy numbers in — just enough to build a country picker without pulling the full catalog. Each country has the same shape it has in Services, so if you already parse countries there, this needs no new code.

Use ?service= to drive a second dropdown: a customer picks a service, and you show only the countries where it actually works — not all of them, most of which would fail at checkout.

# request
curl https://api.codasms.com/v1/countries?service=tg \
  -H "Authorization: Bearer coda_live_..."

# response
{
  "ok": true,
  "filters": { "service": "tg" },
  "count": 188,
  "countries": [
    { "code": "6", "name": "Indonesia", "iso": "ID", "flag": "\ud83c\uddee\ud83c\udde9" }
  ],
  "generated_at": "2026-07-18T09:38:07Z",
  "stale": false
}

A country appears only if it has live, buyable stock. Countries that are sold out, or only available as a manual quote, are left out — so the list never shows something an order would reject.

Create an order

Buys a number and debits your balance. This is the one endpoint that moves money.

The Idempotency-Key header is required. Send a unique value — a UUID is ideal — with every order you place. If a request times out or you lose the connection, retry with the same key: you'll get back the original order, not a second number. This is the difference between a dropped response and a double charge, so your client must set it.

Priority costs more and buys from higher rungs of supply. It's worth it for services where delivery is hard; for most, standard is fine.

# request
curl -X POST https://api.codasms.com/v1/orders \
  -H "Authorization: Bearer coda_live_..." \
  -H "Idempotency-Key: 3f2a9c14-8b6e-4d17-9a2f-1e5c7b0d4a88" \
  -H "Content-Type: application/json" \
  -d '{"service":"tg","country":"6","band":"standard"}'

# response
{
  "ok": true,
  "order_id": 542,
  "number": "628xxxxxxxxx",
  "service": "tg",
  "country": "6",
  "band": "standard",
  "price_cents": 67,
  "status": "active",
  "expires_in_seconds": 1200
}

Use number immediately — request the verification code from whatever service you're verifying, then poll order status for the code.

Retrying safely

Reuse the same Idempotency-Key to retry a request you're unsure completed. A retry after the order succeeded returns the original response unchanged — same order_id, same number, no second charge. A retry while the first is still processing returns 409 with reason: "in_progress"; wait a few seconds and try again. Reusing a key for a different order (a different service or country) returns 422 with reason: "bad_request" — a key belongs to one order, so use a fresh key each time.

Order status

Poll for the code, or cancel for an early refund.

# poll
curl -X POST https://api.codasms.com/v1/orders/status \
  -H "Authorization: Bearer coda_live_..." \
  -H "Content-Type: application/json" \
  -d '{"order_id":542}'

# waiting
{ "ok": true, "order_id": 542, "status": "active", "waiting": true }

# code arrived
{ "ok": true, "order_id": 542, "status": "delivered", "code": "123456" }

# cancel early — refunds immediately
curl -X POST https://api.codasms.com/v1/orders/status \
  -H "Authorization: Bearer coda_live_..." \
  -H "Content-Type: application/json" \
  -d '{"order_id":542,"action":"cancel"}'

{ "ok": true, "order_id": 542, "status": "refunded" }

Poll every 3–5 seconds. Faster wastes your rate limit; codes typically take ~20 seconds. Polling a delivered order is safe and idempotent — it returns the same code.

Cancelling an order that has already delivered will not refund it: you received what you paid for, and the response returns the code instead.

Order lifecycle

Every order reaches a terminal state on its own. A number that receives no code within 20 minutes is expired and refunded automatically by our system — you don't need to poll or cancel for that to happen.

A minimal integration:

• POST /v1/orders → take number and order_id
• Trigger the verification on the target service
• POST /v1/orders/status every 3–5s until delivered or refunded
• Give up early? action: "cancel" to get your money back sooner

Errors

Errors return ok: false and a stable reason string. Branch on reason, not on the HTTP status or on any message text — reason strings are the contract; wording is not.

Some responses also carry detail (human-readable, may change) and refunded: true where money was returned.

Your request

Not available not charged

Bought, then failed refunded

Both carry refunded: true. Your balance is already back.

Ours, not yours

Support

Integration questions, a higher rate limit, a lost key, or an order that looks wrong — contact us. Include your order_id and the key prefix (the first ~18 characters, e.g. coda_live_qKcyrcU2) so we can find it. Never send us your full key.

Not a reseller yet? Apply for access.