Skip to main content
For a user to go through Face Match, you must first fetch a valid session token. This token establishes the authenticity throughout the verification process. Session tokens are valid for 30 days from creation. You do not have to generate one immediately before the user starts — you can create it ahead of time and deliver it asynchronously, such as in an emailed or texted verification link. The user must start and complete Face Match before the token expires.
Face Match sessions cannot be initialized for projects that have groups enabled. If your project uses groups, you will need to use a different project for Face Match verification.

​
Get Session ID

Your application’s server makes an API request to the GET /liveness/session endpoint, passing the account_id of the user you are verifying.
Use https://api.prod.verisoul.ai for production and https://api.sandbox.verisoul.ai for testing. See Environments.
For security, best practice is to fetch the session token from a protected server, never on the client.

​
Parameters

​
Account ID

account_id is your own stable identifier for the user — the same one you use elsewhere in your Verisoul integration. Pass it on every session you can. Linking a session to an account is what turns a one-off verification into a persistent identity. When the session completes it is tied to the account automatically, which:
  • Adds the session to the 1:N deduplication pool. The user’s biometric template becomes searchable, so every later Face Match is compared against it. A future session matching this face under a different account_id is flagged with repeat_face.
  • Creates an account on the real-time platform. This is the same account you would create by calling /session/authenticate. It appears in the dashboard and accumulates account-level signals such as multiple_accounts and accounts_linked.
  • Returns account context on the verify response. List memberships and triggered rules come back from /verify-face, and the decision respects your allow and block lists.
A session that never receives an account_id — not on the session request and not through enrollment — is never added to the deduplication pool. You still get a decision for that one verification, but no future session will ever match against its face, it does not appear as an account, and lists and rules come back as empty arrays.
Repeat verifications of the same user are not multi-accounting. Deduplication compares across account_id values, so an account with several Face Match sessions — retries, step-ups, sign-in authentication, or periodic re-verification — will not raise repeat_face for matching itself. That flag only fires when the same face shows up under a different account_id. Always reuse the same account_id for the same user instead of generating a new one per verification.
account_id must be a non-empty string; an empty or malformed value returns a 400 invalid_account_id error.

​
The id Parameter

Face Match and ID Check share the same /liveness/session endpoint, and the id query parameter is the only thing that distinguishes them.
  • Without id — you get a Face Match session. The user takes a selfie video only. Verify it with /verify-face.
  • With id=true — you get an ID Check session, and the user is additionally asked to upload an identity document.
Only add id=true if you actually want the user to submit an identity document, in which case follow the ID Check integration instead.

​
Referring Session ID

When using Face Match alongside Verisoul’s platform, you can optionally pass a referring_session_id parameter in your session request. This parameter should be the session ID from the user’s current interaction with Verisoul’s platform, before they begin the Face Match verification. By providing this context, Verisoul can make more informed risk assessments during the verification process. Passing a referring session ID provides several benefits:
  • Enhanced risk assessment capabilities for Face Match
  • Access to referring session signals during verification
  • Better detection of impersonation attempts and verification link sharing
For more details on the API parameters, see the session endpoint. To learn about the additional risk signals available when using a referring session ID, refer to the referring session signals.

​
Enrolling an Account ID Later

Some flows run verification before the account exists — for example, verifying a user before they finish signing up. In that case, create the session without an account_id and link it afterwards by calling POST /liveness/enroll with the session_id and the account_id once you have it.
Enrolling has the same effect as passing account_id up front: the account is created and the session joins the deduplication pool. The session must be complete and enrolled within 30 days of creation, and it can only be tied to one account — enrolling a session that already has an account returns session_already_tied_to_an_account.
Whenever you do know the identifier up front, prefer passing account_id on the session request — it is one fewer call and the account context is available the moment the session completes.

​
Next Steps

Once you have obtained a session token, you can proceed to navigate the user to Face Match to complete the verification process.