Automatic OTP Routing and Fallback
Send OTPs through the lowest-cost eligible channel. If delivery isn’t confirmed within eight seconds, SecondFactor tries the next channel automatically.
Manage OTP Delivery Through One API
Connect SMS, WhatsApp, Viber or RCS, then send a verification request with your user’s phone number. SecondFactor selects a route based on destination pricing and the channels available to your account and recipient.
If a channel doesn’t confirm delivery, SecondFactor attempts the next eligible channel within the same request.
Your application handles signup or login. SecondFactor handles channel selection and fallback.
- Attempt 1WhatsApp — lowest-cost eligible channel
- +8.0sNo delivery receipt. Switching channel
- Attempt 2SMS — delivered
- Verify200 OK · code matched
Illustrative route. The channels tried depend on what your account has enabled and what the recipient can receive.
Route by Cost With Automatic Fallback
Use lower-cost channels where available, with another delivery option when a channel doesn’t confirm receipt.
Lowest-Cost Route First
By default, SecondFactor tries the lowest-cost eligible channel for the destination.
Fallback in Eight Seconds
When the first channel doesn’t confirm delivery, the next eligible channel takes over without a second request from your app.
One Send Request
Send one verification request. SecondFactor manages fallback without another API call from your application.
Delivery Logs and Costs
Check the destination, delivery channel, status and cost of each request in your dashboard.
How Routing and Fallback Work
SecondFactor checks the available channels, attempts delivery and handles fallback for each request.
Request an OTP
Post the number in E.164 format to the Verifications endpoint. SecondFactor generates the code and returns a verification SID.
Check Eligible Channels
The engine keeps the channels that are enabled on your account, can reach this number and are allowed by your delivery rules.
Attempt Delivery
The lowest-cost eligible channel is tried first unless a channel preference applies to your pricing plan. Delivery confirmation stops fallback.
Fall Back if Needed
After eight seconds without delivery confirmation, SecondFactor tries the next eligible channel. Attempts stop when delivery is confirmed or all eligible channels have been tried.
Send a Code and Track Delivery
Post the phone number to /Verifications and store the returned verification SID. A 201 response confirms that the request was accepted; delivery happens afterward.
Use webhooks to receive delivery updates. An otp.delivered event identifies the channel that confirmed delivery and the request’s cost so far.
# Send using automatic routing
curl -X POST "https://api.secondfactor.ai/v2/Services/$SERVICE_SID/Verifications" \
-H "X-API-Key: $SF_API_KEY" \
--data-urlencode "To=+9779841000000"
# Delivery webhook (excerpt) { "event": "otp.delivered", "status": "DELIVERED", "channel": "WHATSAPP", "charged": "0.02" }
What Decides the Route
Routing depends on your channel setup, the recipient, destination pricing and delivery rules.
Channels Enabled on Your Account
Only channels you have connected are considered, with their sender and template setup complete. Compare the channels.
What the Recipient Can Receive
Availability depends on the recipient’s messaging apps, device and carrier support.
The Price for the Destination
Eligible channels are ordered by destination cost unless a channel preference applies. See pricing by country.
Your Delivery Rules
Destinations blocked by your delivery rules are refused before anything is sent, and refused sends are not charged.
Track Delivery in Your App and Dashboard
Use webhooks for delivery updates and dashboard logs to investigate individual requests.
Delivery Webhooks
Receive a signed otp.delivered event when a carrier confirms delivery and otp.failed when every channel has failed. Webhook reference.
Verification Status
Fetch a pending verification to check its status. Completed verifications return a 404; use the check response and webhooks to track the outcome.
OTP Logs
Review the destination, channel, status and cost of each request in your dashboard.
Test Routing in the PIE Playground
Use your free credits to send a real OTP, inspect the route it took and verify the code you receive.
Playground requests use real delivery channels. Test with a phone number you own.
More SecondFactor Features
OTP Delivery Logs and Costs
See the channel, delivery status and cost of every OTP request. Learn more →
OTP Template Management
Create templates per channel, track approval and choose one per request. Learn more →
PIE Playground
Send a real OTP, inspect its route and verify the code before you integrate. Learn more →
Frequently Asked Questions
Write to support@secondfactor.ai for anything not covered here.
Can I Choose Which Channel an OTP Uses?+
On per-channel pricing, the optional Channel parameter sets which channel to try first. Other eligible channels remain available for fallback. On blended pricing, SecondFactor ignores this preference and uses the lowest-cost eligible route.
How Long Does SecondFactor Wait Before Switching Channels?+
Eight seconds. If the first channel has not confirmed delivery by then, the next eligible channel is tried.
Do I Need Every Channel Connected for Fallback to Work?+
No. Fallback needs at least two enabled channels that can reach the recipient. With one channel connected, requests are sent on that channel only.
Am I Charged Again When an OTP Falls Back to Another Channel?+
No. Billing is per OTP request: one accepted request is one charge, and fallback happens within that same request. Sending a new code to the same number is a new request and is charged again, so limit how often users can press “send again”.
What Happens When Every Channel Fails?+
SecondFactor sends an otp.failed event to your configured webhook. Review the request in your dashboard before deciding whether to send another code.
How Do I See Which Channel Delivered a Code?+
Check the otp.delivered webhook or the OTP logs in your dashboard. The initial API response arrives before delivery and does not identify the confirmed delivery channel.
Can I Test Routing and Fallback Before Integrating?+
Yes. Use your free credits in the PIE Playground to send a real OTP to your own number, inspect the route it took and verify the code you receive.
Start Testing OTP Routing
Create an account to test routing and fallback with free credits, or talk to our team about the channels and pricing for your destination markets.