Skip to main content
For a user to go through ID Check, 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 ID Check before the token expires.
ID Check sessions cannot be initialized for projects that have groups enabled. If your project uses groups, you will need to use a different project for ID Check verification.

​
Get Session ID

Your application’s server makes an API request to the GET /liveness/session endpoint with two query parameters: id=true, which makes it an ID Check session, and account_id, which links the session to 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

​
The id Parameter

ID Check and Face Match share the same /liveness/session endpoint, and id=true is the only thing that distinguishes them.
  • With id=true — the user takes a selfie video and uploads an identity document. Verify the session with /verify-id.
  • Without id=true — you get a Face Match session. The user only takes a selfie video and is never asked for a document.
If you omit id=true, the session silently becomes a Face Match session. The user will complete it without ever being prompted for their ID, and /verify-id will not return document results.

​
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 face and the identity document become searchable, so every later ID Check is compared against them. A future session matching this face or document under a different account_id is flagged with repeat_face or repeat_id.
  • 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-id, 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 or document, 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 ID Check sessions — retries, step-ups, or periodic re-verification — will not raise repeat_face or repeat_id for matching itself. Those flags only fire when the same face or document 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.

​
Referring Session ID

When using ID Check 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 ID Check. 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 ID Check
  • Access to referring session signals during verification
  • Better detection of impersonation attempts and ID selling
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 KYC 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 ID Check to complete the verification process.