Session filtering

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

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

Authorization

Permission logsKYC is required.

The token can be provided in one of the following ways:

• Header token: <jwt-token> — temporary JWT token
• Field token in the request body — permanent token (UUID)

Access to data in response

For non-admin users, additional permission checks apply:

Permission	Hidden if missing
viewKYCDocumentsOCR	OCR data is replaced with «Access denied»
viewKYCDocumentsChecks	Check results are replaced with «Access denied»
viewKYCDocumentsImages	Images are replaced with «Access denied»

Role-based filtering

• ADMIN — can request sessions of any user (filtered by provided userId)
• OWNER — own sessions + sessions of users in their groups
• SUBORDINATE — sessions of users in 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 as ZIP archive instead of paginated response
isXLS	boolean	false	Export format: true — XLSX, false — CSV
token	string	—	Authorization token (alternative to header)
filters	object	—	Filters object (see below)

Filters

All filters are passed inside the filters object.

range — date range

Filters sessions by creation date.

Field	Type	Description
start	string (ISO 8601)	Range start
end	string (ISO 8601)	Range end
sortOrder	string	Sorting: "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-admin users, the maximum range is limited by company settings

status — session status

String. Possible values:

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

session — session search

String — session UUID or clientId.

• Search by uuid or clientId
• Date range limits are ignored when searching by session

client — client UUID

String. Exact match by clientId.

clientKey — client key search

String. Matches clientKey or clientUser.

schemaId — schema UUID

String (UUID). Exact match by schemaId.

checks — check results

JSON object in format { caption: status }.

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

ocr — OCR search

Array of strings. Searches OCR field values (regex, case-insensitive). Multiple values are combined with OR.

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

type — document type

Array of strings. Regex, case-insensitive. Multiple values are combined with OR.

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

errors — errors

Array of strings. Exact match against task error messages. Multiple values are combined with OR.

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

groupByClientId — group by clientId

String. Filters by client uniqueness:

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

REST API accepts both not-unique and not_unique. GraphQL enum uses not_unique.

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

Export response (zip = true)

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

Request Examples

Basic paginated request

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

Filter 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"
  }
}