SMS Verification API for Virtual Numbers

Quickstart in 3 steps

First sign up for free, top up your balance and get your API key from your profile (API section). In the examples, replace YOUR_KEY with your own key. Requests can be GET or POST: with POST you can send all parameters, including api_key, as form fields (application/x-www-form-urlencoded) in the request body, so the key does not have to appear in URLs or server logs. The two base URLs are equivalent: https://turonay.com/stubs/handler_api.php and https://turonay.com/api/.

1. Check your balance

getBalance returns your balance as ACCESS_BALANCE:amount, which is also the quickest way to confirm that your key works. The amount is in TRY and is the available balance after the amount reserved for open activations.

curl "https://turonay.com/stubs/handler_api.php?api_key=YOUR_KEY&action=getBalance"
ACCESS_BALANCE:125.4000

2. Get a number

service is the service code (wa for WhatsApp) and country is the country id. A successful call returns ACCESS_NUMBER:activation_id:phone. The price is reserved on your balance at this point, not charged yet. If you pass the highest price you accept as maxPrice, no number is taken when the price is higher and WRONG_MAX_PRICE:price is returned.

curl "https://turonay.com/stubs/handler_api.php?api_key=YOUR_KEY&action=getNumber&service=wa&country=62&maxPrice=20"
ACCESS_NUMBER:184213:905301234567

3. Receive the code

Until the code arrives getStatus returns STATUS_WAIT_CODE; once it does you get STATUS_OK:code. The fee is finalised at exactly that moment. Instead of polling you can also use signed webhooks.

curl "https://turonay.com/stubs/handler_api.php?api_key=YOUR_KEY&action=getStatus&id=184213"
STATUS_WAIT_CODE

curl "https://turonay.com/stubs/handler_api.php?api_key=YOUR_KEY&action=getStatus&id=184213"
STATUS_OK:123456

Prefer JSON? getNumberV2

getNumberV2 takes the same parameters as getNumber and returns JSON on success: activation id, phone number, price, currency (949 = TRY), country, end time and operator. activationTime and activationEndTime are in server time (Europe/Istanbul, UTC+3), formatted Y-m-d H:i:s without a time zone. On failure you get the classic plain-text codes (NO_NUMBERS, NO_BALANCE, WRONG_MAX_PRICE:price).

{
  "activationId": "184213",
  "phoneNumber": "905301234567",
  "activationCost": "12.50",
  "currency": 949,
  "countryCode": "62",
  "canGetAnotherSms": true,
  "activationTime": "2026-10-10 12:00:00",
  "activationEndTime": "2026-10-10 12:20:00",
  "activationOperator": "any"
}

Why the Turonay virtual number API?

The goal is a short integration and a cost you can predict.

API methods

Every request carries api_key and action. The table below summarises all actions with typical responses; details are on the API reference page.

Billing: reserve, charge, release

With Turonay you pay for a virtual number when the code arrives, not when the number is allocated, so you do not lose money on activations that are never delivered. The flow has four states:

Price cap: maxPrice

Your balance must cover the number's price, otherwise NO_BALANCE is returned. To protect yourself against price surprises, send maxPrice: if the current price is higher, nothing is purchased and the real price is reported as WRONG_MAX_PRICE:price.

Webhooks: get the code notification on your server

Instead of calling getStatus every second, register an HTTPS URL. When a code arrives or an activation is cancelled, Turonay sends a signed POST to it. The notification is queued as soon as the code is recorded and is typically delivered within 1–2 minutes; polling getStatus remains an alternative and a fallback. You manage the URL and the secret from your profile and can send a test event.

• Signature: HMAC-SHA256 over timestamp.body, sent in the X-Turonay-Signature header.
• Headers: X-Turonay-Event, X-Turonay-Timestamp, X-Turonay-Signature, X-Turonay-Delivery.
• Only https URLs are accepted.
• A failed delivery is attempted up to 8 times with progressive backoff; the same event can arrive again, so write your handler to be idempotent.

POST /your-webhook HTTP/1.1
X-Turonay-Event: code_received
X-Turonay-Timestamp: 1791631200
X-Turonay-Signature: sha256=<hex>
X-Turonay-Delivery: dlv_<id>

signature = HMAC_SHA256(secret, timestamp + "." + body)

For signature verification examples, the payload schema and the retry policy, see the SMS API webhook guide.

Examples in your language

The same flow (get a number, wait for the code, complete) is shown with ready-made examples in three languages.

Coming from another SMS activation API?

Turonay is compatible with the widely used handler_api protocol. If you are coming from another provider that uses it and have written a bot, panel or script against that protocol, switching usually comes down to three changes: the base URL, the API key, and checking service codes and country ids. Test the full flow before going live.

Turonay is an independent service. It is not affiliated with any other provider and does not claim to replace them. Balances cannot be transferred; you top up your Turonay account separately.

Pricing and payment

Prices vary by service and country and are updated continuously, so instead of a fixed list you read the live value with getPrices. For current examples and cost calculation see SMS API pricing. All API amounts are in TRY; on the site you can view TRY, USD or RUB.

You can top up on the payment page by card (Shopier, Stripe), crypto (Cryptomus, Heleket) or bank transfer; which methods are available depends on the currency and region. There is no separate subscription fee for API access.

Resell with your own margin

If you sell SMS verification to your customers through a Telegram bot, a panel or a website, see the SMS reseller page for tiered discounts and margin math.

Developer resources

Ready-made files to speed up your integration:

• OpenAPI definition (openapi.json)
• Postman collection

For the full method and error code reference, open the API reference.

Frequently asked questions

Start integrating

Sign up for free, top up your balance and get your first number in a few minutes.