Operating voice biometrics
Voice biometrics covers the model — enrollment, the challenge phrase, the double verify gate. This page is the operational side: the console your agents and admins work in, the two settings you actually own, and what to do when a verdict comes back weak or suspicious. Everything on this page is tenant-controlled: thresholds, the step-up flag, and enrollment lifecycle live in your organization and nowhere else. The console sits under Verify → Voice biometrics in the dashboard (the “View docs” link in its header points back to this documentation). Every panel in it is backed by a public endpoint, so anything the console does your own integration can also do through the Voice Biometrics API reference.The console surface
Four panels make up the screen. Stat row. Enrolled voiceprint count, then two counters over the recent-events list — verifications that passed, and attempts flagged withdeepfake_detected status. A third stat carries the 7-day false-accept-rate trend as a sparkline: hover any day to read the percentage. This is the number to watch after you loosen the threshold — permissive turning into sloppy shows up here before it shows up anywhere else.
Tenant settings. Two controls, both on PATCH /api/v1/verify/voice-biometrics/settings:
- Confidence threshold — a slider from 0.50 (most permissive) to 0.95 (most strict). This is the cosine-similarity gate described in the concept page, and it really is yours: the value saved here governs live verify decisions. Values outside the range are rejected at the API boundary.
- Auto step-up on low confidence — the
auto_2fa_on_low_confidenceflag. When enabled, a below-threshold result is a signal to escalate to a second factor instead of a hard failure (next section).
passed, failed, or deepfake_detected — plus the timestamp. This is where you read a suspicious attempt back (details in the runbook below).
Enrolled voiceprints. A cursor-paginated table of every stored voiceprint: contact, phone number, confidence at enrollment, consent version, enrollment time, and a per-row action menu. This is also the surface that binds enrollment to verification: every verify call is keyed by contactId, so a caller’s verify attempt only matches against voiceprints enrolled on that contact’s profile — a voiceprint enrolled under one contact never verifies another. The one destructive action lives here too: Delete, which runs DELETE /api/v1/verify/voice-biometrics/{voiceprintId} — a permanent hard delete that revokes the voiceprint and removes the encrypted embedding (GDPR Article 17). After a delete the row leaves this table and GET /enroll/{id} for that voiceprint returns 404, and the contact must re-enroll before the next verify — until it does, verifications come back as no_enrollment.
The auto_2fa_on_low_confidence bridge
A weak biometric verdict is not a verdict against voice biometrics — it is a signal to collect another factor. The flag turns that from an ad-hoc decision into a declared tenant policy.
With the flag off (the default), a verify result below your threshold is a hard fail: result: "failed_no_match" and the flow ends there. With it on, the same score stays a fail at the biometric gate — the similarity gate still decides the verdict — but the flag persists your intent that downstream flows should step up instead of rejecting outright. The setting round-trips on GET /overview, so your integration reads it once and routes accordingly.
The natural follow-on for a stepped-up caller is the Verify profiles and fallback chain flow — issue an OTP on the caller’s reachable channel (SMS → WhatsApp → voice) and run /verify/check. In practice: voice biometrics fails soft, the caller proves possession of a number instead of their voice, and the session still closes. Factor endpoints push, TOTP, and passkey (§4 of the fallback-chains guide) are equally valid step-up legs when the end user is on a device rather than a phone line.
One design rule follows from the shape of the data: the flag only converts low-confidence match outcomes. A failed_spoof / deepfake_detected verdict is never stepped up — that path is a blocked attempt to be investigated, not an uncertain match to be rescued.
How it composes with KBA and the risk verdict
Voice biometrics is one of three Orbit surfaces that answer “is this caller who they claim to be?” — each answering a different part of it:- Voice biometrics proves the speaker’s voice matches the enrolled contact. Per-call, per-contact, operated from this console.
- KBA caller verification proves the caller knows facts on file for the linked contact (email, last-4, full name) within a bounded attempt budget, and writes an audit ledger onto the call record. It needs no prior enrollment.
- The composite pre-send risk verdict is not a verifier at all — it fuses the SMS-pumping, URL-reputation, Verify Fraud Guard, and voice anti-spoof detectors into one 0–100 advisory score. Feed your verify outcome into it as the
voice_biometrics_signalfield when you run the check in your own flow; the composite takes the worst present channel score, so a failed biometric check cannot be washed out by an otherwise-clean aggregate.
Operator runbook
Reading a low-confidence verdict. The verify response carries both the rawconfidence and the resolved thresholds used. Open the event in Recent verification events; its confidence is the number against the threshold you set — a 0.66 against a 0.70 gate is a weak-but-real match, a 0.31 against the same gate is something else. Before lowering a threshold fleet-wide, check whether the failures cluster on one device, ambient noise on one line, or one contact whose enrollment clip was poor (re-enroll that contact rather than loosening the gate for everyone). The false-accept sparkline is the counterweight: any downward threshold change that doesn’t move it is invisible; any that moves it up is a decision you made, not one the platform made.
Evidence on a flagged voice. A deepfake_detected event means the synthetic-speech gate fired, not just a low similarity. The event row gives you the timestamp and the confidence pair for cross-reference; the audit log on the tenant side records the same enrollment, verify, and delete events with their actor. Rotating the contact’s enrollment (delete + re-enroll with a live capture) is the containment action; the flag-on-auto_2fa step-up path deliberately does not apply to this verdict class.
Rollback. Both settings are fully reversible with no migration and no side effects. Save the previous threshold value back over the new one; toggle the step-up flag off. Rolling back a voiceprint is different — a delete is a GDPR erasure and has no undo; the only recovery is re-enrollment with fresh consent text. That asymmetry is why the console asks twice and the API makes delete idempotent but never restorable.
Where this page sits in the model
- Voice biometrics — the conceptual model behind these operations.
- Verification session lifecycle — the OTP session the step-up flow falls back into.
- Verify profiles and fallback chains — where the OTP leg of the step-up is configured.
- KBA caller verification — the knowledge-based alternative when voice enrollment isn’t an option.
- The composite pre-send risk verdict — where
voice_biometrics_signalfolds into the fleet-wide risk score. - Voice Biometrics API reference — the endpoint shapes behind every panel and setting on this page.