Automating SMS Verification With an API (Developer Guide)

If you run QA pipelines or manage many test accounts, buying numbers by hand does not scale. The API lets you do everything the dashboard does: check prices, buy a number, read the code and cancel for a refund.

Get your API key

Log in, open Account settings and copy your API key. Keep it secret: it can spend your balance. You can regenerate it at any time.

The basic flow

1. GET /api/v1/prices?service=telegram: list countries with price, stock and success rate.
2. POST /api/v1/buy with service and country_id (from the prices list): returns an order ID and the number.
3. GET /api/v1/status?id=… every 5 seconds until status is received.
4. POST /api/v1/finish when done, or /api/v1/cancel for a refund if you no longer need it.

Example in Python

import time, requests
BASE = "https://YOUR-DOMAIN/api/v1"
H = {"Authorization": "Bearer YOUR_API_KEY"}

o = requests.post(f"{BASE}/buy", headers=H, data={"service": "telegram", "country_id": 16}).json()
print("Number:", o["order"]["number"])
for _ in range(60):
    s = requests.get(f"{BASE}/status", headers=H, params={"id": o["order"]["id"]}).json()
    if s["order"]["status"] == "received":
        print("Code:", s["order"]["code"]); break
    time.sleep(5)
else:
    requests.post(f"{BASE}/cancel", headers=H, data={"id": o["order"]["id"]})

Already using SMS-Activate style scripts?

Point your existing tool to /stubs/handler_api.php with your API key. getBalance, getNumber, getStatus, setStatus and getPrices are supported, so most tools work by changing only the base URL.

Good practice

• Poll every 5 seconds, not faster.
• Always cancel orders you do not need. Refunds are instant.
• Sort by success_rate, not only by price.
• Respect the concurrent order limit; a limit error means you have too many waiting numbers.

Full reference with every parameter and error code: API documentation.