Skip to main content

​
The Verify fraud gate: score, verdict, and the fallback-constrained chain

The Verify console’s fraud gate is not one control — it is a composite model: a transparent pre-send score computed from network signals about the recipient, a verdict that says allow, step up, or block, and a channel chain the verdict may re-shape before the first code ever goes out. The guide-level walkthrough in Verify profiles: fallback chains tells you which screens to click; this page explains the model those screens render, so you can predict what a gate configuration will do to a send before it runs. Everything here is a tenant-owned control. The gate fires only when your verify profile configures a fraud policy; an unconfigured profile skips the lookup and the scoring entirely and pays zero added latency. Created sessions fall back to platform defaults, and the whole scoring path degrades fail-open when a network-signal source is unreachable.

​
1. The fraud-gate lifecycle — score, gate, decision, route

The gate runs on POST /verify/send, after the profile’s per-recipient velocity caps and before the session row is created:
  1. Collect signals. The send path resolves the recipient’s number intelligence — country, carrier MCC/MNC, roaming state, SIM-swap recency — plus any CAMARA network signals your policy opted into (device location, device reachability, Scam Signal, call-forwarding state).
  2. Score. The signals fold into a composite risk score, 0–100, with machine-readable reason codes naming every contributing signal (weights in §5).
  3. Decide. The policy gates fire in order: geo allow/block lists first, then the MCC/MNC operator blocklist, then the composite score against your thresholds. The verdict is one of allow, step_up, or block.
  4. Route. A block verdict refuses the send synchronously — no session is created. A step_up verdict either proceeds with an audit trail, or — if you enabled channel escalation — re-orders the channel chain so the code is steered onto a stronger factor (§2). An allow verdict proceeds on the chain as configured.
Three refusal shapes sit beside this verdict and look different on purpose:
  • Hard-faux refusals (geo, operator, score-over-block-threshold). The send returns an error and fires verification.fraud_blocked with no session id — it is a policy refusal, not a session failure, so keep it out of your per-recipient lockout counters.
  • SIM-swap pre-flight. A SIM-swap screening rejection returns 403 SIM_SWAP_DETECTED with last_swap_date and block_window_hours in the error details. No session row is created either — wire your step-up logic to the synchronous 403, never to a webhook.
  • Review routing. Every block is also recorded for operators in the admin console’s fraud-review queue (Audit & Security). The review routing is observability layered on the decision — it never changes the verdict, and a dropped review row never un-blocks or re-blocks a send.

​
2. The fallback timeline — chain semantics under the gate

A profile’s channels array is the ordered fallback chain; the async engine advances through it one hop at a time (the verification session lifecycle covers the advance mechanics). The fraud gate interacts with that chain at two points: Before the first hop. A step_up verdict with channel escalation enabled partitions the candidate chain into three tiers:
  • Strong factors (default: sna, totp, push) — promoted to the front. SNA proves live SIM possession over the data bearer; TOTP and push bind to an enrolled device or secret rather than the phone number.
  • Neutral channels — keep their relative order between the tiers.
  • Weak, line-bound channels (default: sms, voice, flashcall) — demoted to the back, or removed entirely when you set suppressWeak. Removal never empties the chain: if every candidate is weak, the guard degrades to demote-only so a send is never stranded with zero channels.
This is the answer to “why voice becomes the fallback target.” Voice is line-bound: after a SIM swap or account takeover, the attacker controls whichever SIM — or forwarded line — now serves the number, and a voice OTP read aloud rings on a line they control. Unconditional call forwarding is the canonical interception vector and carries its own score weight (§5). So when the gate escalates, voice and SMS slide to the back of the chain and a SIM-swap-resistant factor leads; on a clean verdict they stay where you put them, and voice’s last-resort strength — it reaches recipients whose SMS path is filtered — still applies. During the hops. The verdict is computed once at send time. The async fallback engine then advances the chain on delivery failure or timeout without re-scoring — and its own guard rails still apply: an advance re-runs the same pre-dispatch checks, it never regenerates the code, and a successful check on any hop resolves the whole session. A step-up that promoted SNA therefore also changes what “fallback” means for that session: the engine walks a chain whose weakest channels were already pushed to the back. Voice biometrics (§4) is not a delivery channel in this chain — it cannot carry a code. It enters the composite model as a pass-through signal and as a step-up target, not as a fallback hop.

​
3. The code attempts log — per-attempt status coding

Every fallback hop produces its own attempt with its own id, linked back to the parent session, and one row per chain slot in the session’s attempt log. GET /verify/:id/detail returns the log ordered by channel_index — chain order, primary first — and that ordering is the model: the attempt log is the fallback timeline rendered as data. The per-attempt status vocabulary: Each row also carries a provider_message_id for DLR correlation and, on failure, an error_code / error_message pair — so a chain of failed → timeout → delivered reads as: primary rejected, fallback timed out, second fallback delivered. Because the log is keyed by (verification, channel_index), a re-fired hop updates its slot instead of appending a duplicate — the log holds the latest status per hop, not a retry-by-retry audit. Attempt rows are best-effort and fire-and-forget: a missed row degrades the timeline, never the session. Reconcile sessions on their terminal events (verification.approved / verification.failed / expired), and use the log for per-hop diagnosis.

​
4. Voice biometrics — enroll and verify-by-voice-print inline

Voice biometrics proves the person, not possession of a line, which is exactly the gap the fallback chain’s weak-channel problem exposes. The inline flow has two steps:
  1. Enroll. POST /api/v1/verify/voice-biometrics/enroll with a short audio clip, the contact id, and the consent string you captured. The clip is anti-spoof screened before anything is stored; a refused enrollment writes nothing.
  2. Verify. POST /api/v1/verify/voice-biometrics/challenge issues a per-attempt random phrase; POST /api/v1/verify/voice-biometrics/verify submits the recorded phrase against the enrolled voiceprint. The verdict is match AND live — cosine similarity clears your confidence threshold and the anti-spoof gate passes — so a played-back recording of the right voice still fails.
In the composite model, voice biometrics plugs in on two axes:
  • As a step-up target. When the fraud gate escalates, a voice-print check is a second factor that does not depend on the recipient’s line at all — the natural successor to a demoted voice-OTP hop. The tenant setting auto_2fa_on_low_confidence bridges a below-threshold biometric verdict into the same step-up flow.
  • As a composite signal. When you run a biometric challenge yourself, feed its verdict into the pre-send score as the voice_biometrics_signal on POST /risk/score; the composite takes the worst present channel, so a failed biometric check cannot be washed out by otherwise-clean signals.
The full enrollment, challenge, threshold, and erasure model is on the voice biometrics concept page.

​
5. Fraud-score weights — the signal-to-score table

The composite score is additive over the observed signals, capped at 100. These are the current weights and what each signal’s presence discloses about the recipient line: A worked example: a recipient with a ≤24h SIM swap (50), active unconditional call forwarding (40), and roaming (35) scores 100 after the cap — clearing any sane block threshold; without the roaming signal it scores 90, which still clears a typical block threshold and every step-up threshold. Reads to internalize:
  • Only observed negatives score. A signal that could not be determined contributes nothing — fail-open by construction, so an unreachable lookup never invents risk and never absolves it either. Coarse bands (Scam Signal) substitute for individual indicators deliberately, to avoid double-counting swap and forwarding evidence other signals already carry.
  • Thresholds are yours. riskStepUpThreshold and riskBlockThreshold on the profile’s fraud object decide what the score does. Below both, the verdict is allow with an empty reason list.
  • Velocity and geo are gates, not points. The profile’s velocityPerHour / velocityPerDay caps and its geoMode / mccmncBlocklist lists run as their own checks; they refuse a send outright instead of contributing score.
  • Verification session lifecycle — the session state machine, fallback advance mechanics, and per-session events this page’s attempts log feeds.
  • Verify profiles: fallback chains — the screen-by-screen walkthrough for the fraud object and channel chain this model backs.
  • Voice biometrics — enrollment, challenge, and thresholds for the inline voice-print factor.
  • Composite pre-send risk verdict — how verify_signal and voice_biometrics_signal fold across detectors on POST /risk/score.
  • Verify overview — the fraud pre-flight surface and the endpoint rate limits, including verify-fraud-score and verify-fraud-gate.