Фильтрация сессий

Получение списка KYC-сессий с фильтрацией и пагинацией. Поддерживает экспорт в CSV/XLSX архив.

Метод: POST
Путь: kyc/sessions/filter
Content-Type: application/json

Авторизация

Требуется пермишен logsKYC.

Токен передаётся одним из способов:

Заголовок token: <jwt-token> — временный JWT-токен
Поле token в теле запроса — перманентный токен (UUID)

Доступ к данным в ответе

Для неадминов дополнительно проверяются пермишены:

Пермишен	Что скрывается при отсутствии
`viewKYCDocumentsOCR`	OCR-данные заменяются на «Access denied»
`viewKYCDocumentsChecks`	Данные проверок заменяются на «Access denied»
`viewKYCDocumentsImages`	Изображения заменяются на «Access denied»

Ролевая фильтрация

ADMIN — может запрашивать сессии любого пользователя (фильтрует по указанному userId)
OWNER — свои сессии + сессии участников своих групп
SUBORDINATE — сессии участников своих групп + владельцев групп

Параметры запроса

Параметр	Тип	По умолчанию	Описание
`page`	number	1	Номер страницы (минимум 1)
`pageSize`	number	20	Количество сессий на странице (минимум 1)
`zip`	boolean	false	Экспорт в ZIP-архив вместо пагинированного ответа
`isXLS`	boolean	false	Формат экспорта: true — XLSX, false — CSV
`token`	string	—	Токен авторизации (альтернатива заголовку)
`filters`	object	—	Объект с фильтрами (см. ниже)

Фильтры

Все фильтры передаются внутри объекта filters.

range — диапазон дат

Фильтрует сессии по дате создания.

Поле	Тип	Описание
`start`	string (ISO 8601)	Начало диапазона
`end`	string (ISO 8601)	Конец диапазона
`sortOrder`	string	Сортировка: `"ASC"` или `"DESC"`

Даты интерпретируются как календарные дни в UTC
Если указана только одна граница, создаётся окно в один день
Для неадминов максимальный диапазон ограничен лимитом компании

status — статус сессии

Строка. Возможные значения:

idle
processing
success
failed
exception
suspicious
expired — вычисляемый статус: сессии со статусом idle/processing, у которых истёк TTL (createdAt + ttl * 60 <= now)

session — поиск по сессии

Строка — UUID сессии или clientId.

Поиск по uuid или clientId
При поиске по сессии снимаются ограничения по диапазону дат

client — UUID клиента

Строка. Точное совпадение по полю clientId.

clientKey — поиск по ключу клиента

Строка. Ищет совпадение по полям clientKey или clientUser.

schemaId — UUID схемы

Строка в формате UUID. Точное совпадение по полю schemaId.

checks — результаты проверок

JSON-объект вида { caption: status }.

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

ocr — поиск по OCR-полям

Массив строк. Поиск по значениям OCR-полей (regex, case-insensitive). При указании нескольких значений они объединяются через OR (достаточно совпадения хотя бы одного).

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

type — тип документа

Массив строк. Regex, case-insensitive. При указании нескольких значений они объединяются через OR (достаточно совпадения хотя бы одного).

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

errors — ошибки

Массив строк. Точное совпадение по сообщениям об ошибках в задачах. При указании нескольких ошибок они объединяются через OR (достаточно совпадения хотя бы одной).

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

groupByClientId — группировка по clientId

Строка. Фильтрация по уникальности клиента:

Значение	Описание
`"unique"`	Только первые визиты клиента (`isClientNew = true`)
`"not-unique"` или `"not_unique"` или `"false"`	Только повторные визиты (`isClientNew = false`)
`"all"`	Без фильтрации

REST API принимает оба варианта: not-unique (hyphen) и not_unique (underscore). GraphQL enum использует not_unique.

Формат ответа

Пагинированный ответ (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	Описание
`total`	Общее количество страниц
`currentPage`	Текущая страница
`totalItems`	Общее количество сессий

Ответ при экспорте (zip = true)

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

Примеры запросов

Базовый запрос с пагинацией

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

Фильтрация по статусу и клиенту

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

Поиск по OCR и типу документа

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

Поиск по проверкам

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

Только уникальные клиенты

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

Экспорт в XLSX

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

Поиск по UUID сессии

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