> ## 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.

# Биометрия пользователей: поиск по лицу, список блокировки

> Didit прикрепляет биометрические данные лиц к пользователям вендора: поиск 1:N, обнаружение дубликатов, список блокировки и ручная загрузка.



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



      
      

\<pre>

\````# Goal — search, blocklist, and act on User face biometrics

Faces are captured automatically during liveness inside a verification session, and can also be uploaded to an existing User profile when you are migrating users from another provider. You interact with biometrics through three action surfaces: **profile face upload** (attach an imported face to a User), **face search** (find a user by face), and the **Lists API** (blocklist a face so future sessions are auto-declined).

\## 1) Upload a face to an imported User profile

Use this when you already created or imported a User with `vendor_data` and have a trusted face image from your previous provider.

\```bash
\# 1. Get the Didit internal User id from vendor_data
curl https://verification.didit.me/v3/users/user-42/ \
-H "x-api-key: $DIDIT_API_KEY"

\# 2. Upload a base64-encoded face to that profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "comment": "Imported from previous KYC provider"}'
\```

Limits: max 5 faces per User, max 2 MB per image, and the image must contain a detectable face. This enrolls the face for profile evidence and future duplicate/face-search matching. It does not blocklist the face.

\## 2) Face search — 1:N

Use to detect duplicate accounts, identify a face from a CCTV frame, or recognise a returning customer before running new KYC.

\```bash
curl -X POST https://verification.didit.me/v3/face-search/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "user_image=@./selfie.jpg"
\```

Response includes match candidates with similarity scores. Wire your workflow (in the console) to auto-decline / flag / warn on duplicate hits, or call this endpoint directly from your backend before creating a session.

\## 3) Face blocklist — block a user by face

To block a known bad actor going forward, upload their face to a **face-type list** in your application. Any future session whose liveness selfie matches the embedding is auto-declined.

\```bash
\# Upload a face directly to a face-type list (no session needed)
curl -X POST https://verification.didit.me/v3/lists/$LIST_UUID/entries/face-upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "reason": "confirmed_fraud"}'
\```

If the face you want to block came from an existing session, use `POST /v3/lists/{list_uuid}/entries/` with `reference_session_id` instead — the backend extracts the biometric and links the entry back to the session.

Remove a face from the list with the Delete entry endpoint:

\```bash
curl -X DELETE https://verification.didit.me/v3/lists/$LIST_UUID/entries/$ENTRY_UUID/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

The Lists API supports face, document, email, phone, and IBAN list types. See /management-api/lists/overview for the full catalog.

\## 4) Blocklisting after a decline

Declining a session adds the face to no blocklist: the User stays `ACTIVE` and no list entry is written, so a later session with the same face is decided by the workflow's own rules, not by a list match. To block a declined subject, upload the face to a face-type list yourself with the Lists API call above — a decline never does it for you.

\## 5) Where the face lives on the User

\- `portrait_image` on the User entity is a signed URL to the latest approved selfie.
\- Manually uploaded profile faces are listed under the User profile face collection and returned by the profile face list endpoint.
\- `approved_duplicate_status` on each face is one of `NOT_DUPLICATED` / `DUPLICATED`.
\- Embeddings (numeric vectors) are stored separately from the image. Deleting a session deletes the image and, by default, the embedding. An application that opted in to biometric-template retention keeps one image-free template anchored to the User after the session is deleted; it has a finite expiry and is purged on User deletion, a privacy-erasure deletion (deletion_instruction: "privacy_erasure"), or an explicit purge via /v3/biometric-templates/ (see /management-api/biometric-templates/overview).

\## Failure modes

\- `400` from face-search / upload-face — image has no detectable face, multiple faces, or is too low-quality. Re-capture and retry.
\- `404` on Lists API — wrong `list_id` or list deleted.
\- `403` — your role lacks permission on the `lists` resource.
\- `429` — rate-limited.

\## Response shape

See /standalone-apis/face-search and /management-api/lists/upload-face for full schemas. Match objects use `similarity` (0–1) and reference the linked User `vendor_data` when known.

\## Sources of truth

\- /management-api/users/upload-face — attach an imported face to a User profile
\- /standalone-apis/face-search — face search request / response
\- /management-api/lists/upload-face — face blocklist upload
\- /management-api/lists/delete-entry — remove from list
\- /management-api/biometric-templates/overview — templates retained after session deletion
\- /core-technology/face-search/overview — search behaviour
\- /core-technology/liveness/overview — face capture during sessions
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

Вставьте в

Биометрия лиц является основой каждой сущности User. Didit получает изображение лица во время [проверки живости](https://docs.didit.me/ru/core-technology/liveness/overview.md), создаёт векторный эмбеддинг и сохраняет его для четырёх связанных функций: **поиска по лицу 1:N**, **проверки на дубликаты**, **применения списка блокировки** и **повторной биометрической аутентификации**.> [!NOTE]
>
> Сохранённые лица также служат эталоном для [Биометрической аутентификации](https://docs.didit.me/ru/core-technology/biometric-auth/overview.md): создайте сессию биометрической аутентификации с `vendor_data` пользователя и не передавайте `portrait_image`. Didit автоматически использует сохранённое лицо в следующем порядке: сначала лицо из одобренной проверки живости, затем фото с чипа ePassport, затем портрет из документа, удостоверяющего личность, и только после этого лицо, добавленное в профиль вручную.## Как лица привязываются к пользователю**1. Получение во время проверки живости**Когда пользователь проходит сессию с включённой проверкой живости, Didit получает селфи, выполняет пассивную проверку живости, выделяет самое крупное лицо и создаёт векторный эмбеддинг для поиска.**2. Сохранение в профиле пользователя**Лицо связывается с сессией и родительской сущностью User. URL портрета отображается в профиле пользователя как `portrait_image`.**3. Индексация для поиска**Эмбеддинг добавляется в поисковый индекс. Последующие сессии могут выполнять поиск 1:N по этому индексу.## Поиск по лицу (1:N)Поиск по лицу позволяет найти пользователя, загрузив изображение и сравнив его со всеми лицами, зарегистрированными в вашем приложении.Сценарии использования:- **Проверка на дубликаты** при онбординге: не допускать создания двух аккаунтов одним человеком.
- **Обратный поиск**: определение пользователя по кадру с камеры видеонаблюдения или по изображению в ходе расследования мошенничества.
- **Распознавание повторного клиента**: не проводить KYC для вернувшегося клиента.Поиск по лицу запускается автоматически в новых сессиях, если в вашем сценарии включена проверка на дубликаты. Он также доступен как отдельный API:- `POST /v3/face-search/`: [отдельный поиск по лицу](https://docs.didit.me/ru/standalone-apis/face-search.md)## Проверка на дубликатыКаждое новое лицо можно сравнить с уже зарегистрированными лицами, чтобы выявить дубликаты. Didit присваивает каждому лицу значение `approved_duplicate_status`:| Статус | Значение |
| - | - |
| `NOT_DUPLICATED` | Совпадений выше порога сходства не найдено |
| `DUPLICATED` | Лицо совпадает с одним или несколькими лицами из уже одобренной сессии |Сценарии можно настроить так, чтобы:- **Отклонить** сессии с признаком дубликата автоматически.
- **Отправить на проверку**: передать сессию аналитику для ручной проверки.
- **Только предупреждать**: разрешить сессию, но добавить тег риска.Настроить это можно в консоли: *Workflows → \[your workflow] → Face Match / Liveness → Duplicate detection*.## Список блокировки лицОтклонение сессии не добавляет лицо ни в один список блокировки. Чтобы отклонять будущие сессии с тем же лицом, добавьте его в список блокировки самостоятельно: со [страницы Blocklist](https://docs.didit.me/ru/console/blocklist-users.md) или через [Lists API](https://docs.didit.me/ru/management-api/lists/overview.md). Новая сессия, селфи в которой совпадает с этой записью, будет автоматически отклонена.## Загрузка импортированного лица в профиль UserЕсли вы переходите с другого провайдера KYC, сначала можно создать User, а затем привязать к его профилю доверенное изображение лица. User по-прежнему идентифицируется по вашему `vendor_data`, но endpoint загрузки лица использует внутренний идентификатор User в Didit (`didit_internal_id`), чтобы цель была однозначной.**1. Создайте или получите User**Вызовите [`POST /v3/users/create/`](https://docs.didit.me/ru/management-api/users/create) с вашим стабильным `vendor_data` или вызовите `GET /v3/users/{vendor_data}/`, если User уже существует.**2. Извлеките didit\_internal\_id**Ответ по User содержит `didit_internal_id`. В своей системе продолжайте использовать `vendor_data`, а `didit_internal_id` применяйте только в endpoint'ах привязки к профилю.**3. Загрузите лицо**Вызовите [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/ru/management-api/users/upload-face) с изображением лица в кодировке base64.```bash theme={null}
# 1. Create or retrieve the User keyed by your vendor_data
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "previous_provider": "legacy-kyc-vendor" }
  }'

# Response includes:
# { "didit_internal_id": "11111111-2222-3333-4444-555555555555", ... }

# 2. Upload the imported face to the User profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/11111111-2222-3333-4444-555555555555/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'
```Импортированные лица профиля регистрируются в том же индексе лиц, который используется для проверки на дубликаты и поиска по лицу. Они не добавляются в список блокировки автоматически. Чтобы заблокировать известного недобросовестного участника, загрузите его лицо в список типа «лицо».> [!WARNING]
>
> Загружайте только те лица, обработка которых разрешена в соответствии с вашим уведомлением о конфиденциальности и соглашением о миграции. Указывайте идентификаторы исходного провайдера в `metadata` или `comment` только тогда, когда их безопасно показывать вашим специалистам по комплаенсу.### Как происходит блокировка| Триггер | Действие |
| - | - |
| Сессия `DECLINED` | Ничего не добавляется в список блокировки; User остаётся `ACTIVE` |
| Аналитик вручную добавляет лицо в список блокировки из консоли | Лицо добавляется, статус пользователя обновляется в соответствии с политикой |
| Программное добавление через Lists API | Загрузите изображение лица в список блокировки типа «лицо» |### Загрузка лица в список блокировкиЧтобы заблокировать пользователя по лицу программно, загрузите изображение лица в список блокировки типа «лицо» через специальный endpoint [Upload face to list](https://docs.didit.me/ru/management-api/lists/upload-face.md). Didit извлекает биометрический эмбеддинг и добавляет его в соответствующий индекс: любая будущая сессия, селфи в которой совпадает с этим лицом, будет автоматически отклонена.> [!NOTE]
>
> Загрузка лица в профиль и загрузка лица в список блокировки — это разные операции. Загрузка в профиль привязывает доверенное импортированное лицо к User для подтверждения, проверки на дубликаты и поиска по лицу. Чтобы заблокировать лицо и отклонять будущие сессии при совпадении, используйте [Lists API](https://docs.didit.me/ru/management-api/lists/overview.md).### Удаление лица из списка блокировкиУдалите запись в консоли: *Blocklist → Faces → row actions → Remove*, или воспользуйтесь endpoint'ом [Delete entry](https://docs.didit.me/ru/management-api/lists/delete-entry.md).## Сохранённые биометрические шаблоны после удаления сессииУдаление сессии удаляет изображение лица и по умолчанию эмбеддинг лица, поэтому человек выпадает из обнаружения дубликатов и Поиска по лицу. Если вы удаляете сессии сразу после одобрения, но вам по-прежнему нужно выявлять повторные регистрации, включите в приложении [хранение биометрических шаблонов](https://docs.didit.me/ru/console/data-retention.md#хранение-биометрических-шаблонов) или передайте `retain_face_embeddings: true` в вызове удаления.Затем Didit удаляет сессию и все её данные, как обычно, и сохраняет один отдельно управляемый биометрический шаблон лица без изображения, привязанный к пользователю:- Он содержит только числовой шаблон лица и метаданные хранения. Он никогда не содержит изображение лица, видео проверки живости, данные документа, извлечённые поля личности, решение или идентификатор удалённой сессии.
- Он участвует в обнаружении дубликатов, Поиске по лицу, биометрической аутентификации и ваших списках лиц так же, как лицо из действующей сессии. О совпадениях сообщается с `source: "retained_template"`, `vendor_user_id` и `vendor_data` пользователя, а также с `biometric_template_id`.
- Это биометрические данные с конечным сроком действия, указанным в `expires_at`. Шаблон удаляется, когда удалён пользователь, когда удалена любая сессия этого пользователя с `deletion_instruction: "privacy_erasure"`, когда истекает его срок действия или когда вы очищаете его в **Lists → Биометрические шаблоны** или через [Biometric Templates API](https://docs.didit.me/ru/management-api/biometric-templates/overview.md).
- Сессия, созданная без `vendor_data`, не имеет пользователя, к которому можно привязать шаблон. При её удалении сообщается `ineligible_no_vendor_user`, а эмбеддинг удаляется вместе с сессией.
- Сохранённые шаблоны никогда не попадают в список блокировки. Запись в списке блокировки, созданная из удалённой сессии, сохраняет собственную независимую биометрическую запись и собственный жизненный цикл.Шаблоны, привязанные к пользователю, отображаются в профиле пользователя в разделе **Биометрические шаблоны** с действием очистки.## Сводка жизненного цикла лица```mermaid theme={null}
stateDiagram-v2
    [*] --> Enrolled: Face captured during liveness
    Enrolled --> Approved: Session approved
    Enrolled --> Declined: Session declined
    Enrolled --> Duplicated: 1:N search finds match
    Duplicated --> Approved: Allowed by workflow
    Duplicated --> Declined: Rejected by workflow
    Enrolled --> Blocklisted: Face uploaded to a face-type list
    Declined --> [*]: Nothing blocklisted
    Blocklisted --> [*]: Manually removed
    Approved --> [*]: Session deleted (default)
    Approved --> RetainedTemplate: Session deleted with retention enabled
    RetainedTemplate --> [*]: Expiry, User deletion, privacy erasure, or purge
```## Загрузка лица из консолиСотрудники комплаенса могут загружать лица вручную:1) Перейдите в *Users → \[user] → Actions → Upload face*.
2) Выберите изображение. Didit извлекает самое крупное лицо и сохраняет новую запись Face, привязанную к пользователю.
3) Лицо регистрируется как подтверждение профиля, для обнаружения дубликатов и поиска по лицу. Если нужно отклонять будущие совпадающие сессии, используйте раздел списка блокировки.Это полезно, когда:- У вас есть известный портрет клиента, проверенного через офлайн-канал.
- Вы хотите заранее заполнить список блокировки известными недобросовестными участниками из вашей базы данных о мошенничестве.## Конфиденциальность и хранение- Эмбеддинги лиц являются числовыми векторами, а не изображениями. Сами изображения хранятся в зашифрованном объектном хранилище с доступом по подписанным URL. Эмбеддинг лица является биометрическими данными.
- Срок хранения определяется политикой [хранения данных](https://docs.didit.me/ru/console/data-retention.md) вашего приложения. Для сохранённых биометрических шаблонов действует более строгий и ограниченный срок [хранения биометрических шаблонов](https://docs.didit.me/ru/console/data-retention.md#хранение-биометрических-шаблонов).
- Удаление сессии удаляет изображение и по умолчанию эмбеддинг. Если ваше приложение включило хранение биометрических шаблонов, удаление сессии сохраняет шаблон без изображения до истечения срока или очистки.
- Для запроса на право быть забытым по GDPR / CCPA удалите сессии этого человека с `deletion_instruction: "privacy_erasure"` или удалите пользователя: в обоих случаях очищаются и все сохранённые шаблоны. Записи списка блокировки лиц, которыми вы управляете, остаются, пока вы их не удалите.## Следующие шаги> [card] [Поиск по лицу](https://docs.didit.me/ru/core-technology/face-search/overview.md)
>
> Как работает поиск по лицу 1:N.> [card] [Проверка живости](https://docs.didit.me/ru/core-technology/liveness/overview.md)
>
> Проверка живости, которая фиксирует лицо.> [card] [API списка блокировки](https://docs.didit.me/ru/management-api/lists/upload-face.md)
>
> Загрузка лица в список блокировки.> [card] [Биометрические шаблоны](https://docs.didit.me/ru/management-api/biometric-templates/overview.md)
>
> Шаблоны, сохранённые после удаления сессии.> [card] [Список блокировки пользователей](https://docs.didit.me/ru/entities/users/blocklist.md)
>
> Как работает блокировка пользователя.


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