How OTP Verification APIs Work: Buy, Wait, Receive, Cancel
The basic flow behind every virtual number API, explained for developers who are integrating one for the first time.
By the Sabiverify Team • October 8, 2026 • 2 min read
Whichever provider you use, the lifecycle of a virtual-number order is nearly the same. Understanding it makes your integration simpler and more reliable.
The four stages
- Discover. Fetch the list of countries and services, with current prices and availability.
- Buy. Request a number for a specific service and country. The response contains an order ID and the phone number.
- Poll. Use the order ID to check the order status every few seconds until the code arrives or the order expires.
- Finish or cancel. When you have the code, mark the order as complete. If no code arrives, cancel the order so your balance is refunded.
Design tips
- Poll politely. Every 3–5 seconds is plenty. Hammering the API risks rate limits.
- Always set a timeout. Stop polling when the order expires and cancel if no code arrived.
- Make operations idempotent. Cancelling the same order twice should not refund twice — handle repeated responses safely.
- Check the balance before buying. Fail early with a clear message rather than after the call.
- Keep your key secret. Call the API from your server, never from front-end code.
Error handling
Treat these as normal, not exceptional: no numbers available, price changed, balance too low and order expired. Show friendly messages to your users and keep the technical detail in your server logs.
Where to start
Ask Sabiverify support for access to the API documentation available for your account, and test the full buy–poll–cancel loop with small orders before going live.