KYC session status

Purpose

Use this call to read a session after the user has finished the widget, or to poll while it runs. You can also receive the SESSION_COMPLETE webhook and call this method once with the identifier the event carries. Database check verdicts, such as AML screening, are not part of this answer: read them with database check results.

Request

POST <API_BASE_URL>/kyc/session/status. 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.
`sessionId`	string	one of two	The session identifier. A questionnaire record is accepted here too: pass the `questionnaireSessionId` that the `QUESTIONNAIRE_COMPLETE` event carried.
`clientKey`	string	one of two	Your client key, for regular sessions only. A client key always resolves a regular session, never a questionnaire record.

Send either sessionId or clientKey. When both are sent, sessionId identifies the session.

Response

HTTP 200. The body is either the session object or, when you passed a questionnaire identifier, the questionnaire record.

Field	Type	Description
`status`	string	The session status: `idle`, `processing`, `success`, `failed`, `exception`, `expired` or `suspicious`. A running session answers `processing` and an expired one `expired`. Never read it as the `ok` or `error` of an envelope.
`sessionId`	string (uuid)	The session identifier.
`results`	array of object	One entry per step, each with its own status. See the session object.
`errors`	array of string	Session-level error codes.
`secondsToLive`	number	Seconds left before the session expires.

The questionnaire branch. A questionnaire record is recognized by type of questionnaire. Its status is idle or success only, and success means that the form was filled in and committed. It never means that checks came back clean. See two-stage questionnaire, then KYC.

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.
500: An unexpected internal failure. The answer has status of error and the fixed text internal error; nothing in the body helps you branch beyond the code.

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/status" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<your permanent API token>",
    "sessionId": "00000000-0000-0000-0000-000000000000"
  }'

Response:

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