Verification sessions

A verification session ties one end user's document check, liveness check and face match together and returns a single decision. Use it when you need to know that the person holding the phone is the person on the document, not just that each check passed on its own.

Flow

1. Your server calls POST /v1/verifications with a secret key and the customer_ref of the person being verified. The response is the verification (vf_…) plus a session token (dv_tok_…) bound to it.
2. Your app uses that token to call POST /v1/ocr (front and back of the document), POST /v1/fraud/detect and POST /v1/liveness/check exactly as it would for standalone checks. Each result is recorded as a step of the verification.
3. The platform compares the document portrait with the frame the liveness check scored, on the server, and decides. Your app never uploads a selfie for matching.
4. Your server receives a verification.completed webhook, or polls GET /v1/verifications/{id}.

The standalone endpoints keep working unchanged for integrations that only need one check.

Steps and decision

Step	Completed when	Fails when
document	OCR is eligible and a fraud check has run with a clean or needs_review decision	the fraud decision is fraudulent
liveness	is_live is true	is_live is false, with the liveness reason as the reason code
match	the document portrait and the scored liveness frame agree at or above the tenant's face_match_threshold	they do not, or one side has no usable face embedding

The decision is made as soon as it is determined:

Outcome	When
rejected	fraud says fraudulent; liveness failed and no attempts remain; the face did not match and no attempts remain
review	fraud says needs_review (unless the policy lets that through); the match could not be computed
approved	every required step completed and the faces match

A liveness or match failure with attempts left keeps the verification pending, so the app can ask the user to try again. A verification is closed once decided; further calls with its token return 409 verification_closed.

Policy

Defaults come from your tenant configuration and can be overridden per verification in the create request:

{
  "customer_ref": "cust-42",
  "policy": {
    "required_steps": ["document", "liveness", "match"],
    "liveness_mode": "challenge",
    "max_liveness_attempts": 2,
    "review_blocks_approval": true
  }
}

liveness_mode is enforced: a liveness call in a different mode is rejected before any processing.

Billing

Each step bills its own feature exactly as the standalone call does. The verification object itself is free.