Verification sessions

A session is a hosted verification flow. Instead of calling each verify primitive yourself, you create a session for a flow (for example liveness plus face match plus document), hand the user a hosted capture page, and read back a single decision when they finish. This keeps camera capture, retries, and scoring on Sovera's side.

The hosted flow

Your backend calls POST /v1/sessions with the flow you want and an optional reference and subject.
Sovera returns a sessionId, a short-lived clientToken, and a hostedUrl.
You send the user to the hostedUrl (or embed it), where they complete capture. The clientToken authorizes that front end without exposing your API key.
You poll GET /v1/sessions/{sessionId} (or receive a webhook) until status is terminal, then read the decision.
You pull a GET /v1/sessions/{sessionId}/report for the per-check breakdown.

The clientToken and hostedUrl are returned once at creation. The clientToken is short-lived and safe to hand to a browser or app. Your svk_... API key must stay on the server.

Create a session

Requires the sessions:write scope. Record consent before a flow that captures biometrics.

POST

/v1/sessions

curl -X POST https://verify.lioncapventures.com/v1/sessions \
  -H "Authorization: Bearer svk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "flow": "liveness+facematch+document",
    "reference": "signup_18422",
    "subject": { "firstName": "Tapiwa", "lastName": "Moyo" },
    "redirectUrl": "https://app.example.com/verify/done"
  }'

Response (201)

{
  "sessionId": "ses_8f2c1a7b",
  "status": "pending",
  "flow": "liveness+facematch+document",
  "clientToken": "sct_live_short_lived_token",
  "hostedUrl": "https://verify.lioncapventures.com/s/ses_8f2c1a7b",
  "expiresAt": "2026-07-04T18:30:00Z",
  "decision": null,
  "decisionReasons": [],
  "checks": []
}

Name
flow
Type
string
Description
The checks to run, for example liveness, liveness+facematch, or liveness+facematch+document.
Name
reference
Type
string
Description
Your own identifier for this verification, echoed back so you can reconcile it.
Name
subject
Type
object
Description
Optional subject details (name, ID number) used by the flow. PII is tokenized at rest.
Name
redirectUrl
Type
string
Description
Where the hosted flow returns the user after capture.
Name
metadata
Type
object
Description
Arbitrary key-value data you want attached to the session.

Get status

Requires the sessions:read scope. Poll until status is terminal, or subscribe to a webhook so you do not have to poll.

GET

/v1/sessions/{session_id}

curl https://verify.lioncapventures.com/v1/sessions/ses_8f2c1a7b \
  -H "Authorization: Bearer svk_live_xxxxxxxx"

Response

{
  "sessionId": "ses_8f2c1a7b",
  "status": "completed",
  "flow": "liveness+facematch+document",
  "clientToken": null,
  "hostedUrl": "https://verify.lioncapventures.com/s/ses_8f2c1a7b",
  "expiresAt": "2026-07-04T18:30:00Z",
  "decision": "approved",
  "decisionReasons": ["liveness_pass", "facematch_pass", "document_pass"],
  "checks": [
    { "type": "liveness", "status": "pass", "score": 0.98 },
    { "type": "facematch", "status": "pass", "similarity": 0.91 },
    { "type": "document", "status": "pass" }
  ]
}

The decision is one of approved, declined, or review, with decisionReasons explaining why. Treat review as a case for a human, not an automatic pass.

Cancel a session

Requires the sessions:write scope. Cancels a session that has not reached a terminal state.

POST

/v1/sessions/{session_id}/cancel

curl -X POST https://verify.lioncapventures.com/v1/sessions/ses_8f2c1a7b/cancel \
  -H "Authorization: Bearer svk_live_xxxxxxxx"

Session report

Requires the sessions:read scope. Returns the full per-check breakdown for audit and record keeping.

GET

/v1/sessions/{session_id}/report

curl https://verify.lioncapventures.com/v1/sessions/ses_8f2c1a7b/report \
  -H "Authorization: Bearer svk_live_xxxxxxxx"