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 passed 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)

Access to 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 Filtering

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

---

Query 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 the range
end	string (ISO 8601)	End of the 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 status idle/processing 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 on the clientId field.

clientKey — search by client key

String. Searches for a match in the clientKey or clientUser fields.

schemaId — Schema UUID

String in UUID format. Exact match on the schemaId field.

checks — check 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 (at least one match is sufficient).

{
  "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 (a match with at least one is sufficient).

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

groupByClientId — group by clientId

String. Filter by customer uniqueness:

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

The REST API accepts both variants: not-unique (hyphen) and not_unique (underscore). The 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

Response on export (zip = true)

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

---

Example Queries

Basic query with pagination

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

OCR and Document Type Search

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

Search by checks

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

Unique clients only

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