Profiles
Named liveness profiles, strictness presets and per-session overrides
A profile is the complete configuration of a session: the device and handoff it targets, whether the subject follows timed prompts (active) or simply holds still (passive), whether a reference photo is expected, which pipeline stages run, the decision thresholds, and what happens when a provider is unavailable. Pick one by name in POST /liveness/sessions or POST /liveness/analyze; the resolved profile is frozen on the session and returned as config in the report.
GET /liveness/profiles lists the profiles with their stage ids.
Named profiles
| Profile | Device | Handoff | Mode | Reference | Strictness | For |
|---|---|---|---|---|---|---|
desktop-passive | desktop | same device | passive | none | standard | Webcam, subject holds still |
desktop-active | desktop | same device | active | none | standard | Webcam with timed prompts |
desktop-quick | desktop | same device | active | none | standard | Webcam, three short gestures and a screen sequence, about twenty seconds |
desktop-active-idmatch-lenient | desktop | same device | active | upload, optional | lenient | Webcam with prompts and an optional reference photo, looser thresholds |
mobile-passive-qr | phone | QR | passive | none | standard | Phone handoff, subject holds still |
mobile-attested | phone | app | passive | none | standard | Capture in the Verifiables mobile app, frames only, the upload bound to the device attestation (attested capture); iOS today |
mobile-quick-qr | phone | QR | active | none | standard | Default. Phone handoff, three short gestures and a screen sequence, about twenty seconds |
mobile-active-qr | phone | QR | active | none | standard | Phone handoff with the longer, reinforced prompt script (the default until 6 October 2026) |
mobile-active-idmatch | phone | QR | active | upload, required | standard | Phone handoff, capture matched against a reference photo |
mobile-active-idmatch-strict | phone | QR | active | upload, required | strict | The same with the tightest thresholds; cannot pass while the forensic stage is unavailable |
mobile-document-idmatch | phone | QR | active | document, required | standard | Phone handoff: the subject photographs their identity card or passport first, then the three short gestures; the capture is matched against the document's portrait |
mobile-active-flash | phone | QR | active | none | standard | Adds one opt-in prompt step, enabled on request |
mobile-active-steer | phone | QR | active | none | standard | Kept for compatibility: identical to mobile-active-qr |
api-only-video | any | API only | passive | upload, optional | standard | Your backend posts a video |
api-only-frames | any | API only | passive | upload, optional | standard | Your backend posts frames only, no video stages and no ffmpeg needed |
forensics-only | any | any | passive | none | standard | Forensic analysis alone |
Active profiles run a short script of timed prompts, generated by the server for that one session and re-verified from the uploaded media. Every active profile runs the same script family, on a laptop webcam as on a phone; the profiles differ by device, handoff, reference photo and strictness, not by the checks they run. The two quick profiles are the exception: a shorter script of three gestures drawn for the session, a shorter recording and a lighter analysis, with a verdict in seconds rather than minutes. mobile-quick-qr is the default since 6 October 2026; name a reinforced profile (mobile-active-qr, desktop-active and their variants) to keep the longer script. Their thresholds are still being calibrated on real captures. Passive profiles ask the subject to hold still and run the passive checks alone: prefer an active profile whenever the subject can follow prompts. The prompt protocol itself belongs to the hosted capture page and is not part of the public contract.
mobile-document-idmatch takes the reference from the subject's own identity document instead of a photo you upload. Before the selfie, the capture page asks for an identity card in the bank card format (front and back; the French card issued since 2021, most European cards) or a passport (the photo page), and takes each photo by itself once the document fills the frame, sharp and without glare. The server reads the machine readable zone and its check digits on the side that carries it, and cuts the portrait out of the front as the reference; a side it cannot read is asked for again, up to three times. The report says what the zone holds (identity document), and an expired document fails the session. The document is judged on its photo: its chip is not read. A reference upload to such a session is refused.
mobile-active-flash is the exception: it carries one extra opt-in step that no other profile's pool holds and that cannot be switched on through overrides, so talk to us before you use it. mobile-active-steer was a second such profile until 10 September 2026, when the step it carried became part of every active profile; the name is kept so existing links and integrations keep working, and it now resolves to the same configuration as mobile-active-qr. GET /liveness/profiles also returns variants that are not listed here, including one that omits the forensic stage for integrators who run their own.
An active capture takes about a minute of the subject's time, a passive one a few seconds. On an active profile the subject may be asked to do it again, up to three attempts per session, when their images could not be measured reliably (retakes); the bound is the same on every profile and cannot be overridden, and no preset turns an unmeasurable capture into a pass. config.capture.maxDurationSec on the resolved profile is the hard bound the capture page records to; it follows what the profile serves, so it moves if you override the number of prompts.
Profile structure
The resolved profile is returned as config on the session and in the report.
| Field | Meaning |
|---|---|
capture, challenge | What the page records (video and/or frames, resolution, duration bounds) and how many prompts it runs. The prompt kinds and their verification are not documented publicly |
reference | source: none, upload or document (the portrait of the identity document photographed on the capture page); required rejects captures without a reference; forensics runs the forensic stage on it too |
thresholds, strictness | The decision thresholds the preset resolved, echoed so a report can be read against the rules that produced it |
unavailablePolicy | What a required check with status unavailable or error does to the verdict: review, fail or ignore |
stages | The checks that run, in order, and whether each is required. Passive and API-only profiles carry no challenge stages, api-only-frames no video stages, forensics-only the forensic stages alone |
retention, decision | Hours before media artifacts are purged, whether heatmaps are kept, and whether the forensic stages are skipped when the first frame has no face |
Strictness presets
strictness selects a preset of thresholds and an unavailablePolicy: lenient loosens them, standard is the default, strict tightens them and fails a session whose required checks could not run. The resolved values are returned in config.thresholds on the session and in the report; the individual thresholds and their meanings are shared under NDA.
Overrides
overrides in the session body (or the overrides form field of /liveness/analyze, as a JSON string) patches the named profile. Only the keys below are accepted; any other key is rejected with 422, and the stage list cannot be overridden per session.
| Key | Accepts |
|---|---|
strictness | lenient, standard, strict |
mode | passive, active |
reference | source (none, upload), required, forensics |
challenge | steps, 1 to 6, and the timing bounds of a step |
thresholds | Individual threshold keys, within the bounds the API validates |
unavailablePolicy | review, fail, ignore |
retention | artifactsHours, 0 to 720, and keepHeatmaps |
decision | shortCircuitOnNoFace |
A strictness override re-applies the whole preset first; the explicit keys are applied last, so a per-key value always wins over the preset. An opt-in step a profile does not carry is never introduced by an override, whatever the override asks for. The recording bound is re-derived after your overrides, so a script that grew still fits the capture.
{ "profile": "mobile-active-idmatch", "overrides": { "strictness": "strict", "retention": { "artifactsHours": 2 } } }