Filter KYC sessions

Purpose

Use this call to find sessions by date, status, client key, scenario and other criteria, and to export the matching sessions as an archive. The caller needs the logsKYC permission.

Request

POST <API_BASE_URL>/kyc/sessions/filter. 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. Starts at 1.
`pageSize`	number	no	Sessions per page.
`zip`	boolean	no	Set to `true` to order an export instead of a listing. The answer then carries the archive name, and the archive is built after the answer is sent.
`isXLS`	boolean	no	With `zip`, the file inside the archive is XLSX instead of CSV.
`filters`	object	no	The search criteria, see below.

Filters

All criteria go inside the filters object. Criteria combine; leave out the ones you do not need.

Criterion	Meaning
`range`	Creation date. An object with `start`, `end` (dates such as `2026-01-31`) and `sortOrder` (`ASC` or `DESC`). Dates are calendar days in UTC. With only one boundary the window is one day.
`status`	One session status: `idle`, `processing`, `success`, `failed`, `exception`, `suspicious` or `expired`.
`session`	A session identifier. A search by session ignores the date range.
`client`	The client identifier that the platform resolved for the person. Exact match.
`clientKey`	A match on your `clientKey` or `clientUser` field.
`schemaId`	Exact match on the scenario identifier.
`groupByClientId`	A boolean. The contract example sends `false`. Leave it out unless you need it.
`ocr`	An array of strings searched in the recognized document fields. Several values combine with OR.
`type`	An array of document types. Several values combine with OR.
`errors`	An array of error codes of the steps. Several values combine with OR.
`checks`	An object of the form `{ "<check caption>": "<status>" }`.

Response

HTTP 200. One page of sessions.

Field	Type	Description
`status`	string	Always `ok` on this body.
`results.sessions`	array of object	The sessions of this page. Each item is a session object. The order is not defined unless you send `filters.range.sortOrder`.
`results.pageInfo.total`	number	The number of pages, not of sessions.
`results.pageInfo.currentPage`	number	The page you asked for, echoed back.
`results.pageInfo.totalItems`	number	The number of sessions that match the filter.

Export. With zip set to true the answer carries results.archiveName and results.totalSessions instead of sessions. The archive is built after the answer is sent, so the first download attempts can answer not found. Fetch it with download logs archive.

Redaction, not omission. Without the permissions to view document text, checks or images, the matching key of every step arrives as the string Access denied instead of being left out.

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/filter" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<your permanent API token>",
    "page": 1,
    "pageSize": 20,
    "filters": {
      "status": "failed",
      "range": {
        "start": "2026-01-01",
        "end": "2026-01-31",
        "sortOrder": "DESC"
      }
    }
  }'

Response:

{
  "status": "ok",
  "results": {
    "sessions": [
      {
        "sessionId": "00000000-0000-0000-0000-000000000000",
        "status": "failed",
        "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"
          }
        ]
      }
    ],
    "pageInfo": {
      "total": 1,
      "currentPage": 1,
      "totalItems": 1
    }
  }
}