List KYC sessions

Purpose

Use this call for a simple, newest-first listing, for example to show recent sessions in your own back office. For a listing with search criteria and for exports use filter sessions.

Request

POST <API_BASE_URL>/kyc/sessions. 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.
`page`	number	no	The page number.
`pageSize`	number	no	How many sessions per page.
`schemaId`	string (uuid)	no	Return only the sessions of this scenario.

Response

HTTP 200. One page of sessions. This operation always sorts by creation time, newest first.

Field	Type	Description
`status`	string	Always `ok` at the top level. The `status` inside each item is the session status.
`results`	array of object	The sessions of this page, newest first. Each item is a session object.

Redaction, not omission. Without the permissions to view document text (viewKYCDocumentsOCR), checks (viewKYCDocumentsChecks) or images (viewKYCDocumentsImages), the matching key of every step arrives as the string Access denied instead of being left out. An administrator account is exempt.

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/sessions" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<your permanent API token>",
    "page": 1,
    "pageSize": 20,
    "schemaId": "<your scenario id>"
  }'

Response:

{
  "status": "ok",
  "results": [
    {
      "sessionId": "00000000-0000-0000-0000-000000000000",
      "status": "success",
      "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"
        }
      ]
    }
  ]
}