Provider API reference

Getting started

1. Create an account and join the seller programme in the seller hub.
2. Create your API key (starts with pk_) under Seller hub > API. It is shown only once.
3. Add your servers' IP addresses to the allowlist on the same page; when it is set, requests from other IPs are refused.
4. Add your SIMs, set your price and start sending heartbeats. Online SIMs go on sale at once.

Basics

Base URL

https://smsrota.com/provider/v1

Authentication

Authorization: Bearer pk_… header

Format

JSON bodies and responses; amounts in USD as strings ("0.1200")

Rate limit

600 requests per minute per key

Country codes

SMS-Activate country codes (e.g. 16 United Kingdom, 62 Turkey, 187 USA)

Service codes

SMS-Activate service codes (e.g. wa WhatsApp, tg Telegram, go Google)

How it works

1. POST /heartbeat every 25-30 seconds. A SIM silent for 90 seconds stops being sold and lowers your uptime score.
2. Poll GET /orders every 2-5 seconds. A number in waiting status has been given to a buyer.
3. When an SMS reaches the number, forward the text as is with POST /sms. The code is extracted, the buyer sees it at once and your earning is recorded.
4. Earnings become available after a 72-hour hold; withdraw USDT in the panel or with POST /payouts.
5. Forward every SMS that reaches a rented SIM (GET /rentals) with /sms too; the earning is recorded when the rental ends.

Endpoints

{ "phones": ["447700900001", "447700900002"] }

{ "online": 2 }

[
  {
    "id": 9182,
    "phone": "447700900001",
    "service": "wa",
    "status": "waiting",
    "code": null,
    "createdAt": "2026-11-10T09:00:00.000Z",
    "expiresAt": "2026-11-10T09:20:00.000Z"
  }
]

{ "orderId": 9182, "sender": "WhatsApp", "text": "Your WhatsApp code 123-456" }

{ "accepted": true, "code": "123456" }

[{ "id": 311, "phone": "447700900002", "service": "full", "status": "active", "price": "3.0000", "earning": "2.5500", "sms": 4, "endsAt": "2026-11-11T09:00:00.000Z" }]

[{ "id": 7, "phone": "447700900001", "country": "16", "operator": "EE", "services": [], "enabled": true, "online": true, "busy": false, "delivered": 128 }]

{ "sims": [{ "phone": "447700900001", "country": "16", "operator": "EE", "services": ["wa", "tg"] }] }

{ "ids": [7] }

{ "enabled": false }

{ "ok": true }

{ "prices": [{ "service": "*", "country": "16", "price": 0.12 }, { "service": "wa", "country": "16", "price": 0.18 }] }

{ "ok": true }

{ "prices": [{ "country": "16", "dayPrice": 1.5 }] }

{ "ok": true }

{
  "status": "active",
  "score": 88.5,
  "tier": "A",
  "commission": 0.15,
  "balances": { "pending": "12.4800", "available": "41.2000", "deposit": "50.0000", "depositRequired": "62.0000" },
  "sims": { "total": 12, "online": 11, "busy": 3 },
  "hasKey": true
}

{
  "days": [{ "day": "2026-11-10", "orders": 42, "delivered": 37, "earned": "4.4400", "rentals": 1 }],
  "services": [{ "service": "wa", "orders": 30, "delivered": 28, "earned": "3.3600", "successRate": 93.3 }],
  "countries": [{ "country": "16", "orders": 42, "delivered": 37, "earned": "4.4400", "successRate": 88.1 }],
  "sims": [{ "id": 7, "phone": "447700900001", "orders": 9, "delivered": 9, "earned": "1.0800", "successRate": 100, "uptime": 99.2 }]
}

[{ "id": 55, "kind": "earning", "amount": "0.1020", "bucket": "pending", "createdAt": "…" }]

{ "amount": 40, "address": "TQ…" }

{ "id": 18 }

Example code

Ready-made heartbeat, order polling and SMS forwarding. Replace pk_... with your key.

cURL

# Heartbeat
curl -X POST https://smsrota.com/provider/v1/heartbeat \
  -H "Authorization: Bearer pk_..." -H "Content-Type: application/json" -d '{}'

# Open orders
curl https://smsrota.com/provider/v1/orders -H "Authorization: Bearer pk_..."

# Forward an SMS
curl -X POST https://smsrota.com/provider/v1/sms \
  -H "Authorization: Bearer pk_..." -H "Content-Type: application/json" \
  -d '{"phone":"447700900001","sender":"WhatsApp","text":"Your WhatsApp code 123-456"}'

Python

import threading, time, requests

API = "https://smsrota.com/provider/v1"
H = {"Authorization": "Bearer pk_..."}

def heartbeat():
    while True:
        requests.post(f"{API}/heartbeat", json={}, headers=H, timeout=10)
        time.sleep(25)

threading.Thread(target=heartbeat, daemon=True).start()

def on_sms(phone, sender, text):
    # Call this from your modem / SIM bank software for every incoming SMS.
    r = requests.post(f"{API}/sms", json={"phone": phone, "sender": sender, "text": text}, headers=H, timeout=10)
    print(r.json())

while True:
    for o in requests.get(f"{API}/orders", headers=H, timeout=10).json():
        if o["status"] == "waiting":
            print("waiting for SMS on", o["phone"], "for", o["service"])
    time.sleep(3)

Node.js

const API = "https://smsrota.com/provider/v1";
const headers = { Authorization: "Bearer pk_...", "Content-Type": "application/json" };

setInterval(() => fetch(`${API}/heartbeat`, { method: "POST", headers, body: "{}" }), 25_000);

export async function onSms(phone, sender, text) {
  const res = await fetch(`${API}/sms`, { method: "POST", headers, body: JSON.stringify({ phone, sender, text }) });
  return res.json(); // { accepted: true, code: "123456" }
}

Rules and payouts

Price range

$0.02 to $10 per number; $0.10 to $50 per day for rentals.

Commission

By tier: A 15%, B 20%, C 25%. New sellers start at tier B.

Hold

Every earning waits 72 hours; upheld complaints in that time take it back.

Deposit

$50 plus $1 per SIM, filled from 20% of earnings until covered.

Trial

First 14 days: at most 50 open numbers at once and $50 of payouts per day.

Score

Delivery rate (40%), first-SMS time (20%), uptime (20%) and complaint rate (20%). Sales pause below 50.

Payouts

USDT, at least $10. Tiers A and B daily, tier C weekly.

Error codes

401 bad_key

The key is wrong or revoked, or the request came from an IP outside the allowlist.

400 bad_request

The body is missing or invalid; issues names the field.

403 not_seller

The account is not in the seller programme or was shut out.

409 phone_taken

This number belongs to another seller.

400 price_out_of_range

The price is outside the allowed range.

409 payout_limit

Below the minimum payout or over the daily trial limit.

409 payout_too_soon

Your tier's next payout day has not come yet.

403 payout_frozen

Payouts are paused because of your score or account status.

429

Rate limit reached; wait a moment and retry.