Create a KYC session

Purpose

Use this call to start a verification for one user. The platform creates a session from the scenario you built in the editor and lists the steps it expects, each still waiting. Keep sessionId: uploads go against it, and session status reads the result back. Your user then completes the steps in the web widget.

Request

POST <API_BASE_URL>/kyc/session/create. All calls are POST under your API address. Replace <API_BASE_URL> with the API address provided with your access.

Send a permanent API token in the token field of the body, or a user token in the token header. See authentication.

Content type: application/json.

Field	Type	Required	Description
`token`	string (uuid)	if no header	Your permanent API token. Required unless you send a user token in the `token` header.
`schemaId`	string	yes, in practice	The scenario identifier, from the scenario editor. The scenario must already exist: scenarios are created and edited in the dashboard, not through the API.

Response

HTTP 200. The session was created. status is the session status, idle, and results already lists the steps the scenario asks for.

Field	Type	Description
`sessionId`	string (uuid)	The identifier of the session. Every other KYC operation takes it.
`status`	string	The session status, for a new session `idle`. It is not the success flag of the call. See session statuses.
`schemaId`	string (uuid)	The scenario the session was created from.
`clientKey`	string	Your own identifier for the person, echoed back.
`secondsToLive`	number	Seconds left before the session expires. At zero an `idle` or `processing` session is reported as `expired`.
`createdAt`	string (date-time)	When the session was created.
`errors`	array of string	Session-level error codes, symbolic and not prose. Empty on a clean session.
`results`	array of object	One entry per step of the scenario, each `idle` at first, plus a `faces` entry for the face matching of the session, which comes last. See the session object.

The session object also carries further fields that are filled as the session proceeds. They are listed on the session object page.

Errors

400: The body failed validation. The answer has status of error and a details list with one entry per offending field (path, expected, actual).
401: The token is missing, expired or unknown.

A refusal can also come before the operation runs: an address outside your IP allowlist, a token bound to another address, or a body that is not valid JSON. See response format and errors.

Example

Request:

curl -X POST "<API_BASE_URL>/kyc/session/create" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<your permanent API token>",
    "schemaId": "<your scenario id>"
  }'

Response:

{
  "sessionId": "00000000-0000-0000-0000-000000000000",
  "status": "idle",
  "schemaId": "<your scenario id>",
  "clientKey": "<your identifier for the person>",
  "secondsToLive": 3600,
  "createdAt": "2026-01-01T10:00:00.000Z",
  "errors": [],
  "results": [
    {
      "type": "document",
      "status": "idle"
    },
    {
      "type": "selfie",
      "status": "idle"
    },
    {
      "type": "liveness",
      "status": "idle"
    },
    {
      "type": "faces",
      "status": "idle"
    }
  ]
}