> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verisoul.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Initialize Session

> How to fetch a session token for Face Match verification

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.

<Warning>
  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.
</Warning>

## Get Session ID

Your application's server makes an API request to the [GET /liveness/session](/api-reference/face-match/session) endpoint, passing the `account_id` of the user you are verifying.

```
GET /liveness/session?account_id=<your_account_id>
```

<CodeGroup>
  ```javascript Node theme={null}
  try {
      // Create a session token via Verisoul's API
      let response = await fetch(
          `https://api.prod.verisoul.ai/liveness/session?account_id=${accountId}`,
          {
              method: 'GET',
              headers: {
                  'x-api-key': '{VERISOUL_API_KEY}'
              }
          }
      );

      let {session_id} = await response.json();

      // Return the session_id to your client application
      // ...
  } catch (err) {
      console.error(err);
  }
  ```

  ```bash cURL theme={null}
  curl --location 'https://api.prod.verisoul.ai/liveness/session?account_id={YOUR_ACCOUNT_ID}' \
  --header 'x-api-key: {VERISOUL_API_KEY}'
  ```
</CodeGroup>

Use `https://api.prod.verisoul.ai` for production and `https://api.sandbox.verisoul.ai` for testing. See [Environments](/api-reference/introduction#environments).

<Warning>
  For security, best practice is to fetch the session token from a protected server, never on the client.
</Warning>

## Parameters

| Parameter              | Required                 | Description                                                                                                               |
| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `account_id`           | **Strongly recommended** | Your stable identifier for the user. Links the completed session to that account.                                         |
| `id`                   | **Omit**                 | Adding `id=true` turns this into an [ID Check](/verifications/id-check/integration/initialize-session) session.           |
| `referring_session_id` | Optional                 | The user's current Verisoul platform session, for richer risk assessment.                                                 |
| `simulate`             | Optional                 | Forces a specific outcome in sandbox. See [Simulate Face Match](/verifications/face-match/resources/simulate-face-match). |

### 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`](/verifications/face-match/resources/risk-flags).
* **Creates an account on the real-time platform.** This is the same account you would create by calling [/session/authenticate](/api-reference/session/authenticate). It appears in the dashboard and accumulates [account-level signals](/signals-scores/account-vs-session) such as `multiple_accounts` and `accounts_linked`.
* **Returns account context on the verify response.** List memberships and triggered [rules](/action/rules) come back from [/verify-face](/verifications/face-match/integration/verify-and-enroll), and the decision respects your allow and block lists.

<Warning>
  A session that never receives an `account_id` — not on the session request and not through [enrollment](#enrolling-an-account-id-later) — 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.
</Warning>

<Note>
  **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](/verifications/face-match/integration/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.
</Note>

`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](/verifications/id-check/integration/initialize-session) 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](/api-reference/face-match/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](/verifications/id-check/integration/initialize-session) 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](/api-reference/face-match/session#parameter-referring-session-id). To learn about the additional risk signals available when using a referring session ID, refer to the [referring session signals](/verifications/face-match/integration/response-signals#referring-session-signals).

## Enrolling an Account ID Later

<Note>
  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](/api-reference/face-match/enroll) with the `session_id` and the `account_id` once you have it.

  ```bash theme={null}
  curl --location 'https://api.prod.verisoul.ai/liveness/enroll' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: {VERISOUL_API_KEY}' \
  --data '{
      "session_id": "{VERISOUL_SESSION_ID}",
      "account_id": "{YOUR_ACCOUNT_ID}"
  }'
  ```

  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`.
</Note>

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.