Skip to navigation
Identity verification APISessions

Create a session

Creates a hosted verification link for one applicant from a published workflow. The session carries one verification and is spent once submitted. Its configuration is fixed at creation, so later workflow edits do not change a link already sent.

Error codes

errorStatusMeaning
invalid_input400The body failed validation. message names the first problem.
invalid_reference_photo400The reference face photo was not found.
workflow_not_available422The workflow is not published.
user_reference_required422A biometric workflow did not name its subject.
not_enrolled422The subject has no active biometric enrolment and no reference photo was given.
rate_limited429Too many sessions were started. Try again shortly.
Missing or invalid Authorization header401No bearer credential was sent.
Invalid API key401The key is unknown or revoked.
environment_mismatch403The key belongs to an environment this host does not serve.
origin_not_allowed403The request origin is not on the publishable key allowlist.
ip_not_allowed403The caller address is not on the secret key allowlist.
organization_suspended403The organisation is suspended.
secret_key_required403A publishable key was used on a secret-key endpoint.
business_not_approved403A production key was used before the business was approved.

Requires a secret (sk_) key. A publishable key receives 403 secret_key_required.

Authentication

AuthorizationBearer
Send the API key as a Bearer token. Each operation states whether a publishable key is enough or a secret key is required.

Request

This endpoint expects an object.
workflowIdstringRequired1-64 characters
The published workflow to run.
externalUserIdstringOptional<=190 characters
Your reference for the subject. It links the verification to your records and is what a returning applicant resumes by.
metadatamap from strings to anyOptional

Your own correlation fields, carried onto the verification and its webhooks. Bounded: at most 16 KiB, four levels deep and 100 keys.

faceReferenceMediaIdstringOptional<=64 characters

Biometric authentication workflows only: the mediaId of a reference face photo uploaded with type auth_reference.

userDataobjectOptional
What you already know about the subject, to prefill the flow. The applicant can correct every value.
emailstringOptionalformat: "email"<=254 characters
Email the link to this address on your behalf.
businessobjectOptional
For business workflows, the company where you already know it.
expectedIpAddressstringOptional<=64 characters
The IPv4 or IPv6 address you expect the applicant to verify from, compared by the workflow device rules.

Response

The session was created.
sessionobject
A hosted verification session for one applicant.
deliveryobject or null

Whether the link was emailed. Null when no email was given.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
422
Unprocessable Entity Error
429
Too Many Requests Error