> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Поиск по лицу 1:N: JSON отчёта о результатах совпадений > Отчёт Didit о Поиске по лицу 1:N: ID совпавших сессий, процент схожести, флаги списков блокировки и данные для расследования мошенничества. ## Обзор Поиск по лицу представляет собой биометрический поиск **1:N**: Didit находит самое крупное лицо в вашем `user_image` и ищет его по индексу поиска по лицам вашего приложения — лицам, зарегистрированным в сессиях верификации и сохранённых автономных вызовах API, а также лицам, загруженным напрямую в профиль пользователя, и вашим спискам блокировки и разрешений. Он отличается от Сравнения лиц, которое работает в формате **1:1** — Сравнение лиц сопоставляет селфи с фотографией на конкретном документе, тогда как Поиск по лицу отвечает на вопрос: «встречали ли мы этого человека где-либо ранее?». Перед обработкой отчёта важно понять две особенности поведения: * **Отклоняются только совпадения со списком блокировки.** Поле `face_search.status` принимает значение `Declined` только в том случае, если сработало предупреждение `FACE_IN_BLOCKLIST` или `POSSIBLE_FACE_IN_BLOCKLIST`. Обнаружение исключительно дубликатов возвращает `Approved` — анализируйте `matches` и `warnings`, а не только `status`. * **Опциональное сохранение и регистрация.** Если параметр `save_api_request=true` (по умолчанию), вызов сохраняется как сессия типа API, а найденное лицо регистрируется в вашем индексе поиска по лицам. Лица, зарегистрированные через вызовы Поиска по лицу, **исключаются из будущих результатов Поиска по лицу**, благодаря чему повторные поисковые запросы никогда не находят друг друга. Передайте `save_api_request=false` для разового запроса: ничего не сохраняется и лицо не регистрируется в индексе поиска по лицам. ## Где появляются результаты Поиск по лицу представляет собой автономный API. Результаты поиска возвращаются **синхронно, только в ответе на `POST /v3/face-search/`**, в виде единичного объекта `face_search` на верхнем уровне: ```text theme={null} POST /v3/face-search/ ──▶ { "request_id": …, "face_search": { … }, "vendor_data": …, "metadata": …, "created_at": … } ``` Массива во множественном числе `face_searches[]` нигде нет — соглашение об использовании массивов во множественном числе, принятое для `id_verifications[]`, `aml_screenings[]` и `liveness_checks[]` на endpoint решения по сессии, здесь не применяется. Если параметр `save_api_request=true` (по умолчанию), вызов также сохраняется как сессия типа API: * **Business Console** — сессия появляется в вашем списке сессий вместе с изображением, использованным для поиска, совпадениями и предупреждениями. * **`GET /v3/session/{sessionId}/decision/`** — данные можно получить, используя возвращённый `request_id` в качестве идентификатора сессии. Сохранённые данные отображаются как элемент `FACE_SEARCH` в `features[]` и как элемент `liveness_checks[]`, содержащий сохранённые `matches` (с заново подписанными значениями `match_image_url`) и `warnings` — **но не** как объект `face_search`. Если указано `save_api_request=false`, параметр `request_id` представляет собой временный UUID для корреляции: сессия никогда не сохраняется, поэтому её нельзя получить из Console или через endpoint решения. ## Схема Канонические таблицы полей приведены в разделе [Поиск по лицу в справочнике моделей данных](https://docs.didit.me/ru/reference/data-models.md#поиск-по-лицу). Представленная ниже структура отражает то, что endpoint фактически возвращает во время выполнения. ```typescript theme={null} interface FaceSearchResponse { request_id: string; // UUID — the persisted session id when save_api_request=true face_search: { status: 'Approved' | 'Declined'; total_matches: number; // 0-5, length of matches[] matches: FaceSearchMatch[]; // capped at 5, ordered by similarity user_image: { // always present entities: { bbox: [number, number, number, number]; confidence: number; // 0-1, one entry per detected face }[]; best_angle: 0 | 90 | 180 | 270; }; warnings: Warning[]; }; vendor_data: string | null; // echoed from the request metadata: object | null; // echoed from the request created_at: string; // ISO 8601, e.g. "2026-06-12T01:04:42.763237+00:00" } interface FaceSearchMatch { session_id: string | null; // UUID of the matched session; null for non-session matches session_number: number | null; // Console-friendly number; null for non-session matches similarity_percentage: number; // 0-100 source: 'session' | 'imported' | 'list_entry' | 'retained_template'; vendor_data: string | null; // the matched session's, imported profile's, or retained template's User vendor_data vendor_user_id: string | null; // UUID of the linked User; null for list_entry matches and sessions without a User biometric_template_id: string | null; // set only for retained_template matches verification_date: string | null; // "YYYY-MM-DDThh:mm:ssZ"; null for list_entry matches; the retention date for retained_template matches user_details: { full_name: string | null; document_type: string | null; document_number: string | null; } | null; // null when the matched session has no document data match_image_url: string | null; // signed URL when save_api_request=true; raw storage path otherwise; null for retained_template matches status: 'Approved' | 'Declined' | 'In Review' | null; // the matched session's status is_blocklisted: boolean; is_allowlisted: boolean; api_service: 'ID_VERIFICATION' | 'FACE_MATCH' | 'AGE_ESTIMATION' | 'POA' | 'AML' | 'PASSIVE_LIVENESS' | 'DATABASE_VALIDATION' | 'PHONE_VERIFICATION' | 'EMAIL_VERIFICATION' | null; // null when the match comes from a workflow session } interface Warning { risk: string; feature: 'LIVENESS'; // always LIVENESS on this endpoint additional_data: object | null; log_type: 'error' | 'warning' | 'information'; short_description: string; long_description: string; } ``` Примечания к полям: * **Массив `matches[]` содержит не более 5** записей выше порога схожести, отсортированных по убыванию схожести (`search_type=blocklisted_or_approved` сначала ранжирует записи из списка блокировки, затем из списка разрешений, а затем по схожести). * **`source`** указывает, откуда было зарегистрировано совпавшее лицо: `session` — сессия верификации или сохранённый вызов автономного API; `imported` — лицо, загруженное напрямую в профиль пользователя; `list_entry` — лицо, привязанное к одному из ваших списков; `retained_template` — не содержащий изображения [биометрический шаблон](https://docs.didit.me/ru/management-api/biometric-templates/overview.md), сохранённый приложением после удаления исходной сессии. Поля `session_id`, `session_number`, `status` и `api_service` имеют значение `null` для совпадений типа `imported`, `list_entry` и `retained_template`. * **Совпадения типа `retained_template`** содержат `vendor_user_id`, `vendor_data` и `biometric_template_id`; значения `match_image_url`, `user_details` и всех полей, связанных с сессией, всегда равны `null`: сессия, создавшая лицо, больше не существует, а шаблон не содержит изображений или идентификационных данных. Поле `is_blocklisted` всегда имеет значение `false` для сохранённого шаблона; лицо из списка блокировки возвращается отдельно как совпадение типа `list_entry`. Удалить шаблон можно с помощью `DELETE /v3/biometric-templates/{biometric_template_id}/`. * **`api_service`** представляет собой тип автономного API совпавшей сессии (в верхнем регистре, например, `PASSIVE_LIVENESS`) и `null`, если совпавшее лицо поступило из обычной сессии верификации в рамках сценария. * **`user_details`** берётся из верификации документа совпавшей сессии. Для совпадений с `source: imported` эти данные берутся из профиля пользователя (`full_name` заполнено, `document_type`/`document_number` равны null); поле равно `null`, если идентификационные данные отсутствуют (например, в сессиях, где проводилась только проверка живости). * **Предупреждения имеют сокращённый формат** по сравнению с предупреждениями сценариев: поле `node_id` отсутствует. Описанный в документации контракт ответа (`FaceSearchResponseSerializer`) объявляет пять полей: `risk`, `additional_data`, `log_type`, `short_description`, `long_description`; payload во время выполнения дополнительно содержит поле `feature`, которое здесь всегда равно `"LIVENESS"`. См. [Предупреждения Поиска по лицу](https://docs.didit.me/ru/core-technology/face-search/warnings-face-search.md). * **Совпадения с тем же пользователем не исключаются** — в отличие от обнаружения дубликатов в сценариях, автономный endpoint не отфильтровывает предыдущие сессии с тем же `vendor_data`, поэтому возвращающийся легитимный пользователь совпадёт со своими собственными более ранними сессиями. ## Значения статуса Поле верхнего уровня `face_search.status` формируется на основе массива `warnings[]`. Поле `status` на уровне совпадения отражает результат верификации **совпавшей сессии** и является независимым. | Значение | Когда появляется | | - | - | | `Approved` | Предупреждения о нахождении в списке блокировки не сработали. Включает случаи, когда были найдены совпадения-дубликаты — дубликаты являются информационными сигналами, а не причинами для отклонения. | | `Declined` | Сработало предупреждение `FACE_IN_BLOCKLIST` или `POSSIBLE_FACE_IN_BLOCKLIST` — изображение, использованное для поиска, совпало с лицом из вашего списка блокировки лиц. | Примечание: если изображение, использованное для поиска, не содержит лица, которое можно обнаружить, API возвращает HTTP `400` с `{"error": "No face detected in the image"}` **до того**, как будет создан объект `face_search` — статус `Declined` для этого случая отсутствует. При недостатке кредитов возвращается HTTP `403` до любой обработки изображения. ## Примеры ### Approved — совпадение дубликата, нет в списке блокировки ```json theme={null} { "request_id": "5e0c3a1f-7b2d-4c8e-9f10-2a3b4c5d6e7f", "face_search": { "status": "Approved", "total_matches": 1, "matches": [ { "session_id": "1f2e3d4c-5b6a-7980-1122-334455667788", "session_number": 1024, "similarity_percentage": 87.42, "source": "session", "vendor_data": "user-9", "verification_date": "2025-11-20T09:15:00Z", "user_details": { "full_name": "Jane Marie Doe", "document_type": "Passport", "document_number": "X1234567" }, "match_image_url": "https:///face/9c8b7a6d/reference.jpg?signature=...", "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": null } ], "user_image": { "entities": [ { "bbox": [40, 40, 120, 120], "confidence": 0.732973 } ], "best_angle": 0 }, "warnings": [ { "risk": "DUPLICATED_FACE", "feature": "LIVENESS", "additional_data": { "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788", "duplicated_session_number": 1024, "api_service": null }, "log_type": "information", "short_description": "Duplicated face from other approved session", "long_description": "The system identified a duplicated face from another approved session, requiring further investigation." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } ``` ### Declined — совпадение со списком блокировки ```json theme={null} { "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "face_search": { "status": "Declined", "total_matches": 1, "matches": [ { "session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86", "session_number": 323442, "similarity_percentage": 99.99, "source": "session", "vendor_data": "user-1", "verification_date": "2025-01-01T00:00:00Z", "user_details": { "full_name": "Jane Marie Doe", "document_type": "ID", "document_number": "X1234567" }, "match_image_url": "https:///face/3f6a1c2e/reference.jpg?signature=...", "status": "Approved", "is_blocklisted": true, "is_allowlisted": false, "api_service": "PASSIVE_LIVENESS" } ], "user_image": { "entities": [ { "bbox": [40, 40, 120, 120], "confidence": 0.732973 } ], "best_angle": 0 }, "warnings": [ { "risk": "FACE_IN_BLOCKLIST", "feature": "LIVENESS", "additional_data": { "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86", "blocklisted_session_number": 323442, "api_service": "PASSIVE_LIVENESS" }, "log_type": "error", "short_description": "Face in blocklist", "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } ``` ## Связанные разделы * [Предупреждения функции «Поиск по лицу»](https://docs.didit.me/ru/core-technology/face-search/warnings-face-search.md) — все коды предупреждений, которые может возвращать поиск * [Справочник API функции «Поиск по лицу»](https://docs.didit.me/ru/standalone-apis/face-search.md) — параметры запроса и режимы `search_type` * [Модели данных — Поиск по лицу](https://docs.didit.me/ru/reference/data-models.md#поиск-по-лицу) — каноническая схема * [Webhook](https://docs.didit.me/ru/integration/webhooks.md) — payload события `status.updated` для сохранённых сессий > [!NOTE] > > Когда `save_api_request=true`, значения `match_image_url` представляют собой подписанные временные URL — повторно вызовите endpoint решения по сессии с возвращённым `request_id`, чтобы получить актуальные ссылки. Когда `save_api_request=false`, они являются внутренними путями хранилища и недоступны для прямого скачивания. Сохраняйте на своей стороне только идентификатор совпавшей сессии, статус и `similarity_percentage` — не сохраняйте исходное биометрическое изображение. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.