> ## 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: API для обнаружения дубликатов

> Didit ищет лица среди верифицированных пользователей для выявления дубликатов и мошенников. Бесплатно с верификацией, ответ быстрее 2 с.

Поиск по лицу представляет собой мощную функцию, позволяющую искать определенное лицо среди всех ваших одобренных сессий верификации личности. Эта возможность помогает выявлять дублирующиеся аккаунты, предотвращать мошенничество и усиливать меры безопасности.

Промпт интеграции поиска по лицу
        Скопировать промпт в буфер обмена



      
      

\<pre>

\````# Goal
Integrate Didit Face Search (1:N — search a face across your enrolled users + blocklist) into your app.

\# Delivery mode
Face Search is a **standalone API**. It runs against the face index your application has enrolled through prior verifications (sessions with save_api_request=true or Passive Liveness with save_api_request=true), faces uploaded to User profiles, your face lists, and any image-free biometric templates the application retained after deleting sessions (opt-in, see /management-api/biometric-templates/overview). There is no separate Face Search workflow feature.

POST https://verification.didit.me/v3/face-search/
multipart/form-data — x-api-key: YOUR_API_KEY

Required: `user_image` (jpg/jpeg/png/tiff/webp, max 5 MB; PDFs not accepted). The image must contain at least one detectable face (largest bbox wins when multiple).

Optional: `search_type` = "most_similar" (default — dedupe / returning-user) | "blocklisted_or_approved" (blocklist screening).

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-search/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'search_type=most_similar' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```

\# Response shape (singular)
Unlike most features, Face Search returns a **singular** `face_search` object — not a plural array:
\{ request_id, face_search: { status, total_matches, matches: [{ session_id, session_number, similarity_percentage, source, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details, match_image_url, status, is_blocklisted, is_allowlisted, api_service }], user_image: {entities}, warnings: [...] } }

match.source is "session", "imported", "list_entry", or "retained_template". A retained_template hit comes from an image-free biometric template kept after the source session was deleted: session_id, session_number, status, api_service, match_image_url, and user_details are null; vendor_data and vendor_user_id identify the User; biometric_template_id is the template you can inspect or purge via /v3/biometric-templates/{id}/.

\`status` is "Declined" only when at least one blocklist match is found. Pure duplicate matches return "Approved" (informational) — apply your own dedupe policy in app logic.

\# Warnings
Face Search emits risk codes from the LogWarningChoices.FACEMATCH bucket plus blocklist/duplicate semantics:
FACE_IN_BLOCKLIST, POSSIBLE_FACE_IN_BLOCKLIST, DUPLICATED_FACE, POSSIBLE_DUPLICATED_FACE, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-search/warnings-face-search.

\# Failure modes to handle
\- HTTP 400 — no face detected in user_image. Ask the user to retake.
\- HTTP 403 — out of credits.
\- status="Declined" with FACE_IN_BLOCKLIST — definitive blocklist hit; reject.
\- POSSIBLE_FACE_IN_BLOCKLIST — borderline match below the hard threshold; route to manual review.
\- DUPLICATED_FACE — user already verified under a different vendor_data; merge or block according to policy.

\# See also
\- Canonical schema: /reference/data-models#face-search
\- Per-feature report: /core-technology/face-search/report-face-search
\- Risk catalogue: /core-technology/face-search/warnings-face-search
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Вставьте в

Урок Академии по чтению результата верификации доходит до поиска по лицу и списков блокировки на отметке 6:53.[Поиск по лицу и списки блокировки — Академия Didit](https://www.youtube.com/embed/7htTWCWsl60?start=413\&rel=0\&playsinline=1)![Процесс поиска по лицу 1:N в Didit, интегрированный с проверкой живости для выявления дубликатов и совпадений со списком блокировки](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/face-search-liveness.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=0cb5738f8ceaae7891cf13631485c400)## Автоматическая интеграция поиска по лицу> Поиск по лицу автоматически выполняется во время проверок живости в сессиях верификации для обнаружения дубликатов пользователей и сверки со списками блокировки лиц.### Автоматическое обнаружение дубликатовКогда пользователь проходит проверку живости в процессе верификации личности:- Его биометрические данные лица автоматически сравниваются со всеми ранее верифицированными пользователями
- Система выявляет потенциальные дубликаты аккаунтов на основе схожести лиц
- Совпадения помечаются в соответствии с настроенными вами порогами схожести
- Вы можете просматривать потенциальные дубликаты пользователей и принимать по ним меры### Интеграция со списком блокировкиПоиск по лицу легко интегрируется с [функцией списка блокировки](https://docs.didit.me/ru/management-api/lists/overview.md):- Во время верификации лица автоматически проверяются по вашему списку блокировки
- При обнаружении совпадения с лицом из списка блокировки верификация автоматически отклоняется
- Это не позволяет ранее выявленным проблемным пользователям создавать новые аккаунты
- Помогает поддерживать надежность вашего процесса верификации### Селфи, сделанное во время захвата документаПока пользователь фотографирует свой документ, фронтальная камера делает его селфи (Тихий захват). Каждый раз при оценке документа это селфи проходит такой же поиск 1:N, как и селфи проверки живости:- Оно сравнивается с вашим списком блокировки лиц и с уже одобренными пользователями в вашем приложении, с теми же порогами схожести и тем же приоритетом, что и поиск при проверке живости.
- Совпадение со списком блокировки вызывает `FRONT_CAMERA_FACE_IN_BLOCKLIST` (решение всегда «Отклонена») или `POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST` (решение всегда «На проверке»). Совпадение с одобренным пользователем вызывает `FRONT_CAMERA_DUPLICATED_FACE` или `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE`, а также `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH`, если этот одобренный пользователь был верифицирован под другим именем, и `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH`, если в документе, удостоверяющем личность этого пользователя, указана другая дата рождения. См. [предупреждения верификации личности](https://docs.didit.me/ru/core-technology/id-verification/warnings-id-verification.md).
- Совпадения перечисляются в деталях сессии, в карточке верификации личности, и возвращаются в поле `id_verifications[].document_selfie_face_matches` в [решении по сессии](https://docs.didit.me/ru/sessions-api/retrieve-session.md). Используется тот же формат записей, что и в `liveness_checks[].matches`. Поле имеет значение `null` для более старых сессий или если поиск не выполнялся, и пустой массив, если поиск выполнялся, но ничего не нашел. `match_image_url` представляет собой предварительно подписанный URL-адрес с ограниченным сроком действия.
- Используется только самое крупное лицо на селфи и только тогда, когда детектор уверен, что это лицо. Для каждого документа проверяется одно селфи: с лицевой стороны или с обратной стороны, если на селфи с лицевой стороны нет четкого лица.
- Селфи только сравнивается. Его биометрический шаблон никогда не сохраняется, поэтому последующие сессии никогда с ним не сопоставляются. Чтобы заблокировать человека по селфи из сессии, добавьте его в свой список блокировки лиц со страницы сессии.У этого поиска есть собственный переключатель и собственные действия на шаге **Верификация личности**, на вкладке шага **Правила** (**Поиск по лицу при тихом захвате**), либо через `document_selfie_face_search_enabled` и действия `document_selfie_duplicated_face_*` в [конфигурации функций сценария](https://docs.didit.me/ru/management-api/workflows/feature-configs.md#ocr-/-верификация-личности). По умолчанию он включен; для действия при дублированном лице по умолчанию установлено значение Approve (предупреждение все равно фиксируется), а для перекрестных проверок имени и документа по умолчанию установлено значение Review, как и соответствующие действия при проверке живости. Для поиска требуется селфи, поэтому он выполняется только при включенном Тихом захвате. Отключение Поиска по лицу на шаге проверки живости отключает и этот поиск: это отключение относится к лицу человека, поэтому оно распространяется на все селфи сессии.### Правило несоответствия документаПравило **несоответствия документа** (`DUPLICATED_FACE_DOCUMENT_MISMATCH` для селфи проверки живости, `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` для Тихого захвата) помечает дублированное лицо только в том случае, если в документе, удостоверяющем личность совпавшего пользователя, указана другая дата рождения.
Если один и тот же человек предъявляет другой документ, например загранпаспорт после ID-карты, предупреждение не выставляется.
Обновленный документ также не помечается.
Две сессии с одинаковым номером документа из одной и той же страны никогда не помечаются.### Отключение автоматического Поиска по лицуАвтоматический Поиск по лицу по умолчанию включен для каждого шага Проверки живости. Если этого требует ваша политика конфиденциальности, вы можете отключить его для конкретного сценария на вкладке **Правила** шага **Проверка живости** в Business Console (простой и расширенный режимы) или с помощью `face_search_enabled: false` в узле `LIVENESS` или `AGE_ESTIMATION` в [конфигурации функций сценария](https://docs.didit.me/ru/management-api/workflows/feature-configs.md#liveness).При выключенном переключателе для селфи проверки живости по-прежнему выполняется проверка живости и оно сравнивается 1:1 с портретом в документе в рамках Сравнения лиц, но оно никогда не попадает в индекс лиц:- Поиск не выполняется, поэтому сессия не получает решения по дубликату, списку блокировки или списку разрешений, а ее массив `liveness_checks[].matches` остается пустым. Правилам **Дублированное лицо**, **несоответствие имени**, **несоответствие документа** и межорганизационным правилам проверки лиц не к чему применяться, и они скрыты в консоли.
- Для селфи не сохраняется биометрический шаблон, поэтому последующие сессии не могут быть сопоставлены с этой сессией, и для [хранения биометрических шаблонов](https://docs.didit.me/ru/console/data-retention.md#хранение-биометрических-шаблонов) ничего не остается после удаления сессии.
- Селфи не используется для определения общего биометрического человека при межорганизационных проверках.
- Селфи, сделанное во время захвата документа, также не проверяется (риски блокировки или дублирования `FRONT_CAMERA_*` не возникают): это отключение распространяется на все селфи сессии. Собственный переключатель шага верификации личности (см. выше) также может отключить этот поиск независимо.**К какому шагу относится переключатель.** Переключатель находится на том шаге, который выполняет захват селфи, поэтому шаг **Проверка живости** или **Оценка возраста** отвечает сам за себя. У шага **Сравнение лиц** нет собственного переключателя: когда пользователь повторно делает селфи на этом шаге (например, после того как вы попросите его повторно пройти этот шаг), пересъёмка следует настройке шага «Проверка живости», поэтому отказ исключает новое селфи из индекса. Если ваш сценарий разветвляется на несколько шагов Проверки живости, применяется настройка той ветви, через которую фактически прошла сессия, и межорганизационная проверка лица следует настройке этого же шага.Существующие сценарии сохраняют текущее поведение до тех пор, пока вы не отключите эту функцию. Изменение применяется к сессиям, запущенным после сохранения сценария; шаблоны, сохранённые более ранними сессиями, остаются в индексе до тех пор, пока эти сессии не будут удалены или очищены. Переключатель не влияет на отдельный [Face Search API](https://docs.didit.me/ru/standalone-apis/face-search.md), который вы вызываете напрямую.> [!WARNING]
>
> Ваш список блокировки лиц применяется во время верификации с помощью того же поиска 1:N. Если Поиск по лицу выключен на шаге проверки живости, лицо из списка блокировки не будет обнаружено ни на этом шаге, ни по селфи, сделанному во время захвата документа; если Поиск по лицу при тихом захвате выключен на шаге Верификации личности, оно не будет обнаружено по этому селфи.### Доступ через APIФункционал Поиска по лицу также доступен через наш [API](https://docs.didit.me/ru/standalone-apis/face-search.md), что позволяет вам:- Программно отправлять запросы на поиск по лицу
- Интегрировать возможности сравнения лиц в собственные приложения
- Создавать кастомные сценарии выявления мошенничества
- Разрабатывать автоматизированные системы обнаружения дубликатов## Ключевые функции- **Высокая точность**: передовые биометрические алгоритмы обеспечивают надёжные результаты совпадения
- **Настраиваемые пороги**: адаптируйте чувствительность сопоставления под допустимый уровень риска
- **Комплексное сканирование**: выполняйте поиск по всей базе ваших верифицированных пользователей
- **Быстрые результаты**: обрабатывайте поисковые запросы быстро даже при больших базах пользователей
- **Ориентированность на конфиденциальность**: при сопоставлении используются числовые шаблоны лиц, изолированные в рамках вашего приложения; индекс никогда не покидает ваш тенант### Настраиваемые порогиВы можете настроить чувствительность поиска, установив различные пороги для оценок сходства:> [!NOTE]
>
> Эти пороги можно скорректировать в зависимости от допустимого уровня риска и требований безопасности.## Как это работает**1. Извлечение лица**При запуске поиска система обрабатывает эталонное изображение:| Процесс | Описание |
| - | - |
| **Извлечение признаков** | Выделяет черты лица из эталонного изображения |
| **Нормализация** | Стандартизирует данные лица для единообразного сравнения |
| **Проверка качества** | Проверяет качество изображения и чёткость лица |
| **Векторное кодирование** | Создаёт математическое векторное представление лица |**2. Алгоритм сравнения**Система выполняет поиск по всей вашей базе верифицированных сессий:- Сравнивает эталонный вектор лица с **каждым лицом, зарегистрированным в вашем приложении**: лицами из сессий, лицами, загруженными в профили пользователей (User), вашими списками лиц и любыми сохранёнными биометрическими шаблонами
- Использует передовую архитектуру нейросетей, оптимизированную для высокой скорости и точности
- Поддерживает два режима поиска: **наиболее похожие** (ранжированный список) и **заблокированные или одобренные** (с фильтрацией по статусу)
- Быстро обрабатывает большие базы данных благодаря оптимизированной индексации**3. Оценка сходства**Для каждого сравнения рассчитывается процент сходства:| Диапазон оценки | Интерпретация |
| :-: | - |
| **90%+** | Сильное совпадение — с высокой вероятностью один и тот же человек |
| **70–89%** | Возможное совпадение — может потребоваться ручная проверка |
| **Ниже 70%** | Скорее всего, разные люди |Настроенные вами пороги совпадения определяют, какие результаты помечаются системой.**4. Предоставление результатов**Система возвращает полный набор результатов:- **Ранжированный список** потенциальных совпадений, отсортированный по оценке сходства
- **Детали совпадения**, включая ID сессии, дату верификации и данные поставщика
- **Процент сходства** для каждого совпадения
- **Изображения совпадений**, доступные для визуальной проверки
- **Статус в списке блокировки**, указывающий, находится ли найденное лицо в списке блокировки## Удалённые сессии и сохранённые биометрические шаблоныУдаление сессии по умолчанию удаляет её эмбеддинг лица, поэтому человек исключается из индекса и может пройти повторную верификацию без отметки о дубликате. Приложения, которые удаляют сессии вскоре после одобрения, но всё же должны отслеживать повторные регистрации, могут включить [сохранение биометрических шаблонов](https://docs.didit.me/ru/console/data-retention.md#хранение-биометрических-шаблонов). В этом случае Didit сохраняет один биометрический шаблон без исходного изображения, привязанный к сущности User, после удаления сессии, и этот шаблон участвует в Поиске по лицу и автоматическом обнаружении дубликатов точно так же, как лицо из активной сессии.Совпадение с сохранённым шаблоном возвращается со значением `source: "retained_template"`, атрибутами `vendor_user_id` и `vendor_data` пользователя-владельца, а также `biometric_template_id`. Ответ не содержит ID сессии, изображения совпадения, идентификационных данных или статуса сессии, поскольку сессия, в которой было получено лицо, больше не существует. Сохранённые шаблоны никогда не попадают в список блокировки; записи списка блокировки лиц имеют собственную независимую биометрическую запись.Шаблон хранится до наступления планового срока действия, удаления пользователя, запроса на удаление данных в рамках конфиденциальности или явной очистки через [Biometric Templates API](https://docs.didit.me/ru/management-api/biometric-templates/overview.md) либо раздел **Lists → Biometric templates** в консоли.## Процент сходстваПроцент сходства является ключевой метрикой, используемой для выявления потенциальных совпадений:- **Высокий процент (обычно от 90% и выше)**: указывает на высокую вероятность того, что лица принадлежат одному и тому же человеку.
- **Средний процент (70–89%)**: указывает на возможные совпадения, которые могут потребовать дополнительной проверки.
- **Низкий процент (ниже 70%)**: скорее всего, свидетельствует о том, что это разные люди.Точный порог того, что считается «совпадением», можно настроить в соответствии с вашими требованиями безопасности. Повышение порога снижает количество ложных срабатываний, но может увеличить количество ложноотрицательных результатов.## Сценарии использования- **Предотвращение мошенничества**: выявление пользователей, пытающихся создать несколько аккаунтов
- **Улучшенный KYC**: добавление дополнительного уровня проверки к вашему процессу KYC
- **Соответствие нормативным требованиям**: соблюдение требований по выявлению дублирующихся аккаунтов
- **Контроль доступа**: подтверждение подлинности пользователей для доступа в зоны с повышенными требованиями к безопасности
- **Правоохранительные органы**: содействие уполномоченным органам в установлении личностей лиц, представляющих интерес


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.