> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Operate voice biometrics: thresholds, step-up, and the verification console

> Where enrollment and verification actually live day to day — the dashboard console panels, the two tenant-owned settings, how a weak verdict bridges to OTP, and the operator runbook for low-confidence and flagged-voice events.

# Operating voice biometrics

[Voice biometrics](/concepts/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](/api-reference/endpoints/voice-biometrics).

## 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 with `deepfake_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_confidence` flag. When enabled, a below-threshold result is a signal to escalate to a second factor instead of a hard failure (next section).

Save persists both together and refreshes the whole console, so you change the gate and immediately see the effect on the events below it.

**Recent verification events.** The decision ledger: one row per verify call with its confidence score and status — `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](/guides/verify-fallback-chains) 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**](/concepts/caller-verification-kba) 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**](/concepts/risk-verdict-model) 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_signal` field 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.

A contact center typically layers two of them: voice biometrics for enrolled repeat callers, KBA for first-time or fallback identification, and the composite verdict whenever a send or a call is about to commit. Voice biometrics stays optional throughout — the platform never forces a verification through it.

## Operator runbook

**Reading a low-confidence verdict.** The verify response carries both the raw `confidence` 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](/concepts/voice-biometrics) — the conceptual model behind these operations.
* [Verification session lifecycle](/concepts/verification-lifecycle) — the OTP session the step-up flow falls back into.
* [Verify profiles and fallback chains](/guides/verify-fallback-chains) — where the OTP leg of the step-up is configured.
* [KBA caller verification](/concepts/caller-verification-kba) — the knowledge-based alternative when voice enrollment isn't an option.
* [The composite pre-send risk verdict](/concepts/risk-verdict-model) — where `voice_biometrics_signal` folds into the fleet-wide risk score.
* [Voice Biometrics API reference](/api-reference/endpoints/voice-biometrics) — the endpoint shapes behind every panel and setting on this page.