When to use which signal
Each signal answers a different question. Use this section to decide which signals to query at each point in your user flow, and what to do with each result.
Pre-OTP dispatch
This is the most important integration point. Check before sending any SMS or voice OTP.
|
Signal |
What to do |
|
SIM Swap check |
If swapped=true — the number has been moved to a new SIM. Any OTP you send will be received by the attacker. Do not send. Step up or block. |
|
Call Forward check |
If active=true — incoming voice calls are being redirected to another destination. Do not send a voice OTP. Step up or block. |
At login
Query these signals when a user initiates login, before granting access.
| Signal | What to do |
| SIM Swap check | A recent SIM change at login = elevated risk. Flag the session and require additional verification. |
| Device Swap check | New IMEI at login = flag the session. Combined with SIM Swap = high confidence ATO attempt. |
| Call Forward check | Active forwarding at login = possible OTP interception in progress. Block or step up. |
Before high-value transactions
Run all three signals before confirming any payment, transfer, or sensitive account change.
| Condition | Recommended action |
| Any signal positive | Reject the transaction and require identity re-verification through an alternative channel. |
| SIM Swap + Device Swap | Block immediately. This combination is the strongest network-level indicator of account takeover. |
| All three positive | Lock the account, alert the user through a pre-registered backup channel, and queue for human review. |
maxAge parameter guidance
The maxAge parameter (SIM Swap and Device Swap only) controls how far back the check looks. Choosing the right window depends on your use case.
| maxAge value | Recommended for |
| 240 minutes (4h) | Default. Good for most login and OTP pre-check scenarios. |
| 1440 minutes (24h) | Recommended for high-risk actions: payments, account recovery, privilege escalation. |
| 2400 minutes (40h) | Maximum. Use for onboarding / KYC flows where you want the broadest safety window. |