RingVerify API

Buy SMS verification numbers programmatically — the same numbers, prices and wallet as the website, from your own code.

Your API key

Log in to generate and manage your API key.

How it works

Three steps: get a key, top up your wallet, call the API. Numbers cost the same as on the website (provider cost × 1.40) and are charged to your wallet at purchase.

1

Get an API key

Log in, open your dashboard, and find the API access section. Click Generate API key and copy it — the full key is shown only once. If you lose it, regenerate it (the old key stops working immediately).

2

Top up your wallet

Top up from the dashboard (Binance, or instant USDT BEP20; card payments coming soon). API buys are charged to this wallet — if the balance does not cover the price, the buy is rejected.

3

Call the API

Buy a number with GET /api/v1/number, then poll GET /api/v1/status until the SMS code arrives. See the endpoints below.

⚠ No replacement — API numbers are final sale

API numbers are charged at purchase and are final. If a number never receives a code, there is no free replacement and no refund — the number simply expires after 20 minutes. This is different from website orders, which are refunded automatically if no code arrives. Only use the API if you accept this. Cancelling a number releases it but also gives no refund.

Base URL & authentication

All endpoints live under:

https://revenuering.duckdns.org/ringverify/api/v1/

Send your key in one of two ways — as a query parameter or as a Bearer token. Both work on every endpoint.

GET /api/v1/balance?api_key=YOUR_API_KEY GET /api/v1/balance Authorization: Bearer YOUR_API_KEY

Every response is JSON. Amounts are in units: 1 unit = $0.0001 (so $1.00 = 10,000 units). Prices shown on the website in Rs. use 1 USD = Rs. 290.

Endpoints

GET /api/v1/balance

Check your wallet balance.

GET /api/v1/balance?api_key=YOUR_API_KEY Response (200): {"balance": 100000}

GET /api/v1/number

Buy one number immediately. The wallet is charged at purchase.

ParameterRequiredDescription
serviceYesService code, e.g. wa (WhatsApp), tg (Telegram), go (Google).
countryYesCountry ID, e.g. 187 (USA), 66 (Pakistan), 16 (UK), 60 (Bangladesh). See /api/v1/prices for all pairs.
operatorNoOperator option ID. Omit for the cheapest option.
maxPriceNoMaximum price in USD. The cheapest option at or below this price is picked; if none qualifies, the request fails with MAX_PRICE_EXCEEDED.
minPriceNoMinimum price in USD. Only options at or above this price are considered; if none qualifies, the request fails with MIN_PRICE_EXCEEDED.
GET /api/v1/number?service=wa&country=66&api_key=YOUR_API_KEY Response (201): {"id": 42, "phone": "+923001234567", "service": "wa", "country": "66", "cost": 56, "otpToken": "9f2c4a1e8b6d4f0a3c5e7b9d1f3a5c7e9"}

cost is what was charged to your wallet, in units. The number stays active for 20 minutes.

OTP link (v2.14): every bought number also returns an otpToken. Open https://revenuering.duckdns.org/ringverify/otp.html?token=<otpToken> in any browser — no login needed — and the code appears there when it arrives. Give the link to your customer, not the API key: anyone holding the link can see that number's code.

GET /api/v1/status

Check an order’s status and read the SMS code when it arrives. Poll every few seconds until status is received.

GET /api/v1/status?id=42&api_key=YOUR_API_KEY Response (200) — still waiting: {"id": 42, "phone": "+923001234567", "service": "wa", "country": "66", "status": "waiting", "code": null, "cost": 56} Response (200) — code arrived: {"id": 42, "phone": "+923001234567", "service": "wa", "country": "66", "status": "received", "code": "483920", "cost": 56}

Possible statuses: waiting, received, confirmed, cancelled, expired.

GET /api/v1/cancel

Cancel a waiting number and release it. No refund — API numbers are final sale. Numbers can only be cancelled 2 minutes after purchase.

GET /api/v1/cancel?id=42&api_key=YOUR_API_KEY Response (200): {"ok": true, "id": 42, "status": "cancelled", "refunded": false, "message": "Number cancelled. No refund — API numbers are final sale."}

GET /api/v1/prices

The full price list — every service and country, with the cheapest price per pair. Same data as the website’s live prices.

GET /api/v1/prices?api_key=YOUR_API_KEY Response (200): {"items": [{"service": "wa", "serviceName": "WhatsApp", "countryId": "22", "countryName": "Pakistan", "price": 56, "count": 530, "rate": 0.92, "optionsCount": 3}], "total": 15759}

maxPrice and minPrice (USD) filter the list to pairs whose cheapest price is within the range.

Errors

HTTPErrorMeaning
400INVALID_REQUESTMissing or invalid parameters.
400INVALID_SERVICE_OR_COUNTRYThat service/country pair is not available.
400INVALID_OPERATORUnknown operator option for this pair.
400INVALID_IDThe id parameter is missing or not a number.
401INVALID_API_KEYMissing, wrong, or regenerated API key.
402INSUFFICIENT_BALANCEWallet balance does not cover the price. Top up and retry.
404NOT_FOUNDNo order with that id belongs to your key.
409INVALID_STATUSThat action is not available for this order any more.
409EARLY_CANCEL_DENIEDNumbers can only be cancelled 2 minutes after purchase.
400MAX_PRICE_EXCEEDEDNo option for this pair costs at most maxPrice USD.
400MIN_PRICE_EXCEEDEDNo option for this pair costs at least minPrice USD.
429RATE_LIMITEDMore than 60 API requests per minute for this key. Slow down.
502NO_NUMBERS / PROVIDER_ERRORNo numbers left for that pair, or the provider failed. Retry or pick another pair.

Rate limits

At most 60 API requests per minute per key (HTTP 429 beyond that). Number purchases are additionally limited by the provider to 1 per second — buy requests are queued and served in order, so a burst of buys simply takes a few seconds each.

Example — full flow with curl

KEY=YOUR_API_KEY BASE=https://revenuering.duckdns.org/ringverify/api/v1 # 1. Check balance curl "$BASE/balance?api_key=$KEY" # 2. Buy a WhatsApp number in Pakistan curl "$BASE/number?service=wa&country=66&api_key=$KEY" # 3. Poll until the code arrives curl "$BASE/status?id=42&api_key=$KEY"

Questions? Contact support on WhatsApp, Telegram, or email.

WhatsApp