Developer API

Automate phone verification with simple GET requests. Pass your API key in the URL — just like you're used to.

Base URLhttps://YOUR_DOMAIN/api/v1
Auth?key=YOUR_API_KEY (or header Authorization: Bearer KEY)

Generate your key in the dashboard → API section.

Note: the API currently supports temporary numbers only — rent-number API coming soon.

Endpoints

GET/api/v1/balance?key=KEY

Your wallet balance

GET/api/v1/countries?key=KEY

List available countries

GET/api/v1/apps?key=KEY&country=USA

Apps for a country with your prices

GET/api/v1/number?key=KEY&country=USA&app=WhatsApp

Buy a number (reserves funds)

GET/api/v1/sms?key=KEY&id=ORDER_ID

Poll for the SMS code / status

GET/api/v1/cancel?key=KEY&id=ORDER_ID

Cancel & refund if no code yet

GET/api/v1/history?key=KEY&page=1&limit=20

Your past numbers + codes, paginated

GET/api/v1/codes?key=KEY&id=ORDER_ID

Every code received on one order

Quick start

  1. 1 · Check your balance

    curl "https://YOUR_DOMAIN/api/v1/balance?key=YOUR_API_KEY"

  2. 2 · Buy a number

    curl "https://YOUR_DOMAIN/api/v1/number?key=YOUR_API_KEY&country=USA&app=WhatsApp"

    Returns data.id (your order id) and data.number.

  3. 3 · Poll for the code

    curl "https://YOUR_DOMAIN/api/v1/sms?key=YOUR_API_KEY&id=ORDER_ID"

    status.code = 1000 with data.sms when the code arrives; 2000 while waiting.

  4. 4 · Cancel if needed

    curl "https://YOUR_DOMAIN/api/v1/cancel?key=YOUR_API_KEY&id=ORDER_ID"

History

Page through every number you have ordered, newest first. limit tops out at 100, and status optionally filters (completed, waiting_for_sms, cancelled, …).

curl "https://YOUR_DOMAIN/api/v1/history?key=YOUR_API_KEY&page=1&limit=20"

{ "status": { "code": "1000", "message": "Success" },
  "data": [ { "id": 123, "number": "12096496116", "app": "WhatsApp", "country": "USA",
              "status": "completed", "sms": "481920", "code_count": 1, "price": 0.38,
              "created_at": "2026-09-25T10:03:55.000Z" } ],
  "pagination": { "page": 1, "limit": 20, "total": 348, "pages": 18 } }

Codes are retained for 30 days; older rows return sms: null.

Webhooks

Instead of polling, set a webhook URL in dashboard → API → Webhook and we POST each code to your server the moment it arrives. Answer 2xx within 10 seconds; failures retry 5 times (30s, 2m, 10m, 1h, 6h), and every attempt is listed in your delivery log.

POST https://your-server.com/hooks/sms
X-TRO-Event: sms.received
X-TRO-Timestamp: 1758800000
X-TRO-Signature: sha256=<hmac>

{ "event": "sms.received", "order_id": 123, "number": "12096496116",
  "app": "WhatsApp", "country": "USA", "code": "481920",
  "status": "completed", "mode": "temp", "price": 0.38,
  "received_at": "2026-09-25T10:04:11.000Z" }

Verify the signature before trusting a payload — it is HMAC_SHA256(your_secret, "<X-TRO-Timestamp>." + raw_body), hex-encoded:

// Node
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET)
  .update(req.get('X-TRO-Timestamp') + '.' + rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.get('X-TRO-Signature')));
# PHP
$expected = 'sha256=' . hash_hmac('sha256', $_SERVER['HTTP_X_TRO_TIMESTAMP'] . '.' . $raw, $secret);
$ok = hash_equals($expected, $_SERVER['HTTP_X_TRO_SIGNATURE']);

Response format

{
  "status": { "code": "1000", "message": "Success" },
  "data": { "id": 123, "number": "12096496116", "app": "WhatsApp",
            "country": "USA", "status": "waiting_for_sms", "sms": null, "price": 0.38 }
}

Codes: 1000 = success, 2000 = error/waiting. Rate limit: 120 requests/min per key.

Get your API key