OTP Route API reference

Authentication

Create API keys in the dashboard under Developer → API keys. Keys start with or_live_ and are shown once. Send the key as a Bearer token (or in an X-API-Key header). Keep keys server-side.

curl https://otproute.com/api/v1/balance \
  -H "Authorization: Bearer or_live_xxxxxxxxxxxxxxxxxxxx"

Errors

Errors return a non-2xx status and a JSON body with a stable code and a human-readable message.

{
  "error": { "code": "insufficient_balance", "message": "Insufficient balance: this activation costs $0.20" },
  "detail": "Insufficient balance: this activation costs $0.20"
}

Rate limits

Every account is pay as you go and gets the same limits, applied per account across all keys: 300 requests per minute, up to 10 API keys and up to 5 webhook endpoints. Activation creation is additionally protected by velocity controls. Prefer webhooks over tight polling loops — a poll every 5 seconds per open activation is plenty.

Sandbox

Sandbox accounts return simulated phone numbers (in the fictional 555 range) and deliver a simulated code after roughly 15 seconds. Wallet debits and refunds behave exactly like production, so you can test billing logic end to end. Responses include "sandbox": true. Ask support to enable sandbox on a development account.

Balance

{ "object": "balance", "balance": …, "balance_cents": …, "currency": "USD", "formatted": "…" }

Services

{ "object": "list", "data": [ { "id": "telegram", "name": "Telegram" }, { "id": "google", "name": "Google" } ] }

Countries

{ "object": "list", "data": [ { "id": "us", "name": "United States", "dial": "+1" } ] }

Prices

{ "object": "price", "service": "telegram", "country": "us", "price": 0.2, "price_cents": 20, "currency": "USD", "available": 118 }

Activations

An activation rents a temporary verification number for one service and waits for the code. You only pay if the code arrives: the price is held from your wallet when you create it, and if no SMS arrives before expires_at (about 20 minutes) or you cancel, the full price is refunded to your wallet automatically.

{
  "id": "act_3f9c1e0b7a2d4c5e8f10",
  "object": "activation",
  "status": "received",
  "service": "telegram", "service_name": "Telegram",
  "country": "us", "country_name": "United States",
  "phone_number": "+15550100123", "number": "+15550100123",
  "code": "482913",
  "sms_text": "Telegram code: 482913",
  "price": 0.2, "price_cents": 20,
  "sandbox": false, "source": "api",
  "created_at": 1793338200, "expires_at": 1793339400,
  "received_at": 1793338241, "cancelable_after": 1793338320
}

curl -X POST https://otproute.com/api/v1/activations \
  -H "Authorization: Bearer $OTPROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service":"telegram","country":"us","max_price":0.50}'

import os, time, requests
API = "https://otproute.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['OTPROUTE_KEY']}"}

act = requests.post(f"{API}/activations", headers=H,
                    json={"service": "telegram", "country": "us"}).json()
while act["status"] == "pending":
    time.sleep(5)
    act = requests.get(f"{API}/activations/{act['id']}", headers=H).json()
print(act["status"], act.get("code"))

const API = "https://otproute.com/api/v1";
const H = { Authorization: `Bearer ${process.env.OTPROUTE_KEY}`, "Content-Type": "application/json" };

let act = await (await fetch(`${API}/activations`, { method: "POST", headers: H,
  body: JSON.stringify({ service: "telegram", country: "us" }) })).json();
while (act.status === "pending") {
  await new Promise(r => setTimeout(r, 5000));
  act = await (await fetch(`${API}/activations/${act.id}`, { headers: H })).json();
}
console.log(act.status, act.code);

Dedicated numbers

Dedicated US/CA numbers start from $1.95/month and are rented and renewed from the dashboard, paid from your wallet. The API exposes them for messaging automation; renew_price is the USD amount of the next renewal.

{ "object": "list", "data": [ { "id": "num_8a1f…", "object": "number", "number": "+14155550142", "phone_number": "+14155550142",
  "country": "US", "status": "active", "term": "month12", "renew_price": …, "renews_at": 1801114200, "auto_renew": true } ] }

{ "id": "msg_51c…", "object": "message", "status": "sent", "to": "+14155550199", "text": "Your ticket #4821 is resolved.", "price": … }

Webhooks

Register HTTPS endpoints under Developer → Webhooks, choose events (or all), and use Send test to verify your handler. Every event has the same envelope:

{
  "id": "evt_9b7d0c…",
  "type": "activation.sms_received",
  "created": 1793338241,
  "data": { …activation object… }
}

Verifying signatures

Each request carries X-OTPRoute-Signature: t=<unix>,v1=<hex>, where v1 is HMAC-SHA256 of "<t>.<raw body>" keyed with the endpoint's signing secret (whsec_…). Compare in constant time and reject timestamps older than 5 minutes. Also sent: X-OTPRoute-Event and X-OTPRoute-Delivery (unique — use it to de-duplicate).

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance=300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts, sig = int(parts["t"]), parts["v1"]
    if abs(time.time() - ts) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

import crypto from "node:crypto";

export function verify(rawBody, header, secret, tolerance = 300) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  const ts = Number(parts.t);
  if (Math.abs(Date.now() / 1000 - ts) > tolerance) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${ts}.`).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Delivery & retries

Respond with any 2xx within 10 seconds. Failed deliveries are retried with backoff (30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 6 h). Redirects are not followed. Endpoints must resolve to public IP addresses. The delivery log in the dashboard shows status codes and the last error for every attempt.