An OTP API that plans for the supplier that fails.
Every SMS supplier has bad hours: a carrier rejects a sender ID, a route degrades, delivery receipts go quiet. Our OTP API sends the code through an ordered list of SMS suppliers, moves to the next one when an attempt fails or times out, and can fall back to email - behind two REST endpoints. For general messaging, see the Messaging API.
Quick answer
An OTP API is a pair of endpoints that sends a one-time passcode and verifies the code a user enters. The Flowstates OTP API sends across multiple SMS vendors with sub-second failover and automatic email fallback, so codes still arrive when a route degrades, and every attempt is logged for investigation.
Why OTP codes go missing
Most OTP failures are not outages. They are partial: one country, one carrier, one sender type. A single-supplier integration has nowhere to send the next attempt.
Route degradation
A route keeps accepting messages but delivers late or not at all. The API returns success, the user never sees the code.
Sender and carrier filtering
Carriers rewrite or block sender IDs and filter content. What works in one country is rejected in the next.
Unreliable receipts
Delivery receipts can be late, missing or wrong, so waiting on a receipt alone is a poor failover signal. The verify step is the reliable one.
Ordered failover. Email when SMS will not.
One send call. You set the supplier order; when an attempt fails we move to the next. If every SMS attempt fails, the same code can go by email.
One API call. If SMS delivery fails across all configured vendors, the OTP is automatically sent via email - ensuring your customer always receives their code.
Answers to the failover questions developers ask
OTP traffic runs on its own routing path, separate from marketing sends, with its own supplier list and audit trail.
When does failover trigger?
When a supplier rejects the message, returns an error or does not respond in time. Delivery receipts alone are not treated as proof either way.
Which suppliers?
Use our routes, bring your own supplier accounts, or mix both. The API calls stay the same.
What happens if every SMS route fails?
If you passed an email address, the code is sent by email with no extra integration.
Kept apart from marketing
OTPs do not queue behind campaign traffic and use their own sender and supplier configuration.
What can I audit?
Each send, retry and verify attempt is logged with the supplier used, timing and outcome.
The SMS verification workflow: two endpoints, three steps.
Send
POST the user's phone number and an optional email fallback. We generate, store and dispatch the code.
Fail over
We try your SMS suppliers in the order you set, moving on when an attempt fails, then fall back to email if needed.
Verify
POST the code the user entered. We check it, record the attempt and return success or a typed error.
OTP API FAQ
What is an OTP API?
An OTP API is a pair of endpoints: one sends a one-time passcode to a user and one verifies the code they enter. The API owns code generation, expiry, attempt limits and delivery, so your application only has to call send and verify.
How does the Flowstates OTP API differ from sending an SMS yourself?
A plain SMS send has one route and no verification state. The OTP API cascades across multiple SMS vendors with sub-second failover, falls back to email when SMS is not arriving, and tracks every attempt per request so failures can be diagnosed instead of guessed.
Which channels are used to deliver codes?
SMS as the primary channel, with automatic email fallback. Channel order and per-country vendor order are configured for your traffic during onboarding.
How long does integration take?
Two REST calls: POST /v1/otp/send returns a request_id, and POST /v1/otp/verify checks the code against it. Most teams integrate in a day; the API reference is published in our docs.
Can I control code length and expiry?
Yes. Code length and time-to-live are request parameters, and resend and attempt limits are set per account so you can match your own security policy.
What happens when one SMS vendor degrades?
The cascade moves to the next configured route automatically, and email fallback triggers if the code still isn't confirmed as delivered. Flowstates operates the gateway under a 99.99% gateway SLA and investigates route-level failures on your behalf.
Check your OTP failover against your real traffic.
We will review your current OTP routes, countries and failure points before you change anything.