Session filtering

Retrieving a list of KYC sessions with filtering and pagination. Supports export to CSV/XLSX archive.

• Method: POST
• Path: kyc/sessions/filter
• Content-Type: application/json

---

Authorization

Permission logsKYC is required.

The token is transmitted in one of the following ways:

• Header token: <jwt-token> — temporary JWT token
• The token field in the request body is a permanent token (UUID)

Accessing data in the response

For non-admins, permissions are additionally checked:

Permission	What is hidden when absent
viewKYCDocumentsOCR	OCR data is replaced with «Access denied»
viewKYCDocumentsChecks	Check data is replaced with «Access denied»
viewKYCDocumentsImages	Images are replaced with «Access denied»

Role-based filtering

• ADMIN — can request sessions of any user (filters by specified userId)
• OWNER — their own sessions + sessions of participants in their groups
• SUBORDINATE — sessions of participants of their groups + group owners

---

Request parameters

Parameter	Type	Default	Description
page	number	1	Page number (minimum 1)
pageSize	number	20	Number of sessions per page (minimum 1)
zip	boolean	false	Export to ZIP archive instead of paginated response
isXLS	boolean	false	Export format: true — XLSX, false — CSV
token	string	—	Authorization token (alternative to header)
filters	object	—	Object with filters (see below)

---

Filters

All filters are passed within the filters object.

range — date range

Filters sessions by creation date.

Field	Type	Description
start	string (ISO 8601)	Start of range
end	string (ISO 8601)	End of range
sortOrder	string	Sort order: "ASC" or "DESC"

• Dates are interpreted as calendar days in UTC
• If only one boundary is specified, a one-day window is created
• For non-admins, the maximum range is limited by the company limit

status — session status

String. Possible values:

• idle
• processing
• success
• failed
• exception
• suspicious
• expired — calculated status: sessions with idle/processing status, whose TTL has expired (createdAt + ttl * 60 <= now)

session — search by session

String — session UUID or clientId.

• Search by uuid or clientId
• When searching by session, date range restrictions are removed

client — Client UUID

String. Exact match by clientId field.

clientKey — search by client key

String. Searches for a match by clientKey or clientUser fields.

scenarioId — Scenario UUID

String in UUID format. Exact match by scenarioId field.

checks — audit results

JSON object of the form { caption: status }.

{
  "checks": { "Liveness": "success" }
}

ocr — search by OCR fields

Array of strings. Search by OCR field values (regex, case-insensitive). If multiple values are specified, they are combined with OR (at least one match is sufficient).

{
  "ocr": ["John", "Doe"]
}

type — document type

Array of strings. Regex, case-insensitive. If multiple values are specified, they are combined with OR (it is sufficient for at least one to match).

{
  "type": ["passport", "id_card"]
}

errors — errors

Array of strings. Exact match for error messages in tasks. If multiple errors are specified, they are combined with OR (it is enough for at least one to match).

{
  "errors": ["face_not_found", "document_expired"]
}

groupByClientId — grouping by clientId

Row. Filtering by client uniqueness:

Value	Description
"unique"	Only first client visits (isClientNew = true)
"not-unique" or "not_unique" or "false"	Only repeat visits (isClientNew = false)
"all"	No filtering

---

Response format

Paginated response (zip = false)

{
  "status": "ok",
  "results": {
    "sessions": [
      {
        "sessionId": "...",
        "clientId": "...",
        "status": "success",
        "results": [...],
        "errors": [...],
        "version": 1,
        "spent": 2.5,
        "createdAt": "2026-03-19T12:00:00.000Z",
        "schemaId": "...",
        "clientKey": "...",
        "clientUser": "...",
        "isClientNew": true,
        "secondsToLive": 300,
        "responseTime": "2026-03-19T12:00:01.000Z"
      }
    ],
    "pageInfo": {
      "total": 5,
      "currentPage": 1,
      "totalItems": 42
    }
  }
}

pageInfo field	Description
total	Total number of pages
currentPage	Current page
totalItems	Total number of sessions

Response on export (zip = true)

{
  "status": "ok",
  "results": {
    "archiveName": "kycLogs_2026-03-19_12_00_00_000Z_42.zip",
    "totalSessions": 42
  }
}

---

Examples of queries

Basic query with pagination

{
  "page": 1,
  "pageSize": 20,
  "filters": {
    "range": {
      "start": "2026-03-01",
      "end": "2026-03-19",
      "sortOrder": "DESC"
    }
  }
}

Filtering by status and client

{
  "page": 1,
  "pageSize": 10,
  "filters": {
    "status": "failed",
    "clientKey": "user@example.com"
  }
}

Search by OCR and document type

{
  "page": 1,
  "pageSize": 10,
  "filters": {
    "ocr": ["John", "Smith"],
    "type": ["passport"]
  }
}

Search by checks

{
  "page": 1,
  "pageSize": 10,
  "filters": {
    "checks": {
      "Liveness": "success",
      "Face match": "failed"
    }
  }
}

Only unique clients

{
  "page": 1,
  "pageSize": 50,
  "filters": {
    "groupByClientId": "unique",
    "range": {
      "start": "2026-03-01",
      "end": "2026-03-19"
    }
  }
}

Export to XLSX

{
  "zip": true,
  "isXLS": true,
  "filters": {
    "range": {
      "start": "2026-03-01",
      "end": "2026-03-15"
    },
    "status": "success"
  }
}

Search by session UUID

{
  "filters": {
    "session": "550e8400-e29b-41d4-a716-446655440000"
  }
}