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

# API биометрических шаблонов

> Управляйте биометрическими шаблонами лиц без изображений, которые хранятся после удаления сессии: просмотр, фильтрация и удаление через API Didit.



Промпт для API биометрических шаблонов
        Скопировать промпт в буфер обмена



      
      

\<pre>

\`Manage the biometric templates my Didit application retains after deleting verification sessions.

What a biometric template is:
When an application opts in (face_retention_policy: "retain_until_user_deleted", or retain_face_embeddings: true on a delete call), deleting a KYC session deletes the session and all of its data but keeps ONE image-free face biometric template anchored to the session's User. The template keeps duplicate-face, multi-account, biometric-authentication, and list matching working for that person. It contains the numeric face template plus retention metadata only — never the face image, liveness video, document data, extracted identity fields, the decision, or the deleted session's id. It is biometric data: not anonymous, not transient, and not deleted with the session. It has a finite expires_at.

Endpoints (base https://verification.didit.me, header x-api-key: YOUR_API_KEY; API keys only — Console user tokens get 403):
\- GET  /v3/biometric-templates/            — paginated list (limit/offset). Filters: vendor_data (substring, case-insensitive), vendor_user_uuid, status, source_type, retained_from, retained_to (ISO 8601), ordering (retained_at | -retained_at | expires_at | -expires_at; default -retained_at). Purged templates are not listed.
\- GET  /v3/biometric-templates/count/      — {"count": n} with the same filters.
\- GET  /v3/biometric-templates/{uuid}/     — one template.
\- DELETE /v3/biometric-templates/{uuid}/   — purge one template. 200 {"uuid": "...", "outcome": "purged" | "already_purged"}.
\- POST /v3/biometric-templates/delete/     — bulk purge. Body: {"template_uuids": ["..."]} OR {"delete_all": true} plus optional filters (vendor_data, vendor_user_uuid, status, source_type, retained_from, retained_to) that narrow delete_all. 200 {"results": [{"uuid": "...", "outcome": "purged" | "already_purged"}]}.

Template object:
\{
"uuid": "<template id>",
"vendor_user_uuid": "<User id>",
"vendor_data": "<the User's current vendor_data, resolved live>",
"source_type": "session_delete" | "automatic_retention" | "backfill",
"provenance_reference": "<opaque UUID, not the deleted session id>",
"retention_policy": "delete_with_session" | "retain_until_user_deleted",
"retention_override": true | false | null,
"retained_at": "<ISO 8601>",
"expires_at": "<ISO 8601>",
"retained_by": "<principal id: application UUID for API keys, Console member id, or service:...>",
"retained_by_type": "API_KEY" | "CONSOLE_USER" | "SYSTEM",
"instruction_class": "operational_session_delete" | "privacy_erasure",
"instruction_source": "api" | "console" | "automatic_retention" | "backfill" | "privacy_erasure" | "explicit_template_purge" | "vendor_user_delete" | "expiry" | "reconciliation" | "migration" | "system",
"instruction_id": "<your instruction_id or a Didit-generated one>",
"held_out_of_use": false,
"status": "pending" | "active" | "expired" | "held_out_of_use" | "purge_pending" | "purge_failed" | "purged",
"purged_at": null | "<ISO 8601>"
}
Only status "active" templates that are not held_out_of_use, not past expires_at, and whose User still exists take part in matching.

Purge points (all remove the template from matching and delete the stored template):
\- DELETE /v3/biometric-templates/{uuid}/ or POST /v3/biometric-templates/delete/
\- POST /v3/users/delete/ for the owning User
\- any session deletion for that User sent with deletion_instruction: "privacy_erasure"
\- automatic expiry at expires_at
Switching the application policy back to delete_with_session does NOT purge existing templates — purge them explicitly.

Failure modes:
\- 400 — {"template_uuids": ["This field is required unless delete_all is true."]} on bulk purge without a selector; invalid filter values.
\- 403 — {"detail": "You do not have permission to perform this action."} (Console user token, or key not allowed).
\- 404 — {"detail": "Biometric template not found."} on GET of an unknown or purged template.
\- 503 — {"detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable."} The template moves to status purge_failed and is already excluded from matching; repeat the purge.

Every retain and purge attempt, including failures, is recorded on Didit's audit trail with the acting principal, instruction class, instruction_source, instruction_id, and outcome.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\</pre>



      
      

Вставьте в

По умолчанию при удалении сессии верификации также удаляется эмбеддинг лица, который использовался для [Поиска по лицу 1:N](https://docs.didit.me/ru/core-technology/face-search/overview.md) и обнаружения дубликатов в этой сессии. Если вашему приложению нужно, чтобы обнаружение дубликатов продолжало работать после удаления сессии, оно может включить **хранение биометрического шаблона**. В этом случае Didit удаляет сессию и все её данные обычным образом, но сохраняет отдельно управляемый биометрический шаблон лица без изображений, привязанный к [Пользователю](https://docs.didit.me/ru/entities/users/overview.md) этой сессии.Biometric Templates API позволяет увидеть, какие шаблоны хранит ваше приложение, по какой причине и до какого срока, а также удалить их в любой момент. Каждый шаблон также отображается в Business Console в разделе **Lists → Biometric templates** и в профиле пользователя-владельца.> [!WARNING]
>
> Сохранённый биометрический шаблон является биометрическими данными. Он не анонимен, не временен и не удаляется вместе с сессией. Он хранится до запланированного истечения срока хранения, более раннего срока, установленного применимым законодательством, удаления Пользователя, запроса на удаление персональных данных или явного удаления. Включайте хранение только тогда, когда указания вашего контролёра данных и уведомление о конфиденциальности это предусматривают.## Как создаётся шаблон| Триггер | `source_type` | Откуда берётся инструкция |
| - | - | - |
| Вы удаляете сессию в приложении с включённым хранением или отправляете `retain_face_embeddings: true` в [Delete Session](https://docs.didit.me/ru/sessions-api/delete-session.md) или [Batch Delete Sessions](https://docs.didit.me/ru/management-api/sessions/batch-delete.md) | `session_delete` | `instruction_source: api` или `console` |
| Для сессии в приложении с включённым хранением истекает [общий срок хранения данных](https://docs.didit.me/ru/console/data-retention.md), установленный вашим приложением | `automatic_retention` | `instruction_source: automatic_retention` |
| Бэкфилл, выполняемый Didit по вашей инструкции, для сессий, удалённых до включения хранения | `backfill` | `instruction_source: backfill` |Для сохранения шаблона обязательна привязка к Пользователю. Сессия, созданная без `vendor_data`, не имеет Пользователя, поэтому шаблон для неё сохранить нельзя: удаление возвращает `ineligible_no_vendor_user`, а эмбеддинг удаляется вместе с сессией.## Что содержит шаблон| Сохраняется | Никогда не сохраняется |
| - | - |
| Числовой шаблон лица, используемый для сравнения | Изображение лица, видео проверки живости, изображения документов, кадрированные портреты и любые другие медиафайлы |
| Новый случайный `uuid` шаблона и непрозрачный `provenance_reference` | Идентификатор, номер, решение, извлечённые идентификационные поля или payload признаков удалённой сессии |
| Владелец-Пользователь (`vendor_user_uuid`); `vendor_data` определяется по Пользователю при чтении шаблона и никогда не копируется | Состояние списка блокировки, предыдущие совпадения, метки мошенничества или утверждения об идентичности между организациями |
| `retained_at`, `expires_at`, `retention_policy`, `retention_override`, `instruction_class`, `instruction_source`, `instruction_id`, `retained_by`, `retained_by_type` | Адреса электронной почты субъектов, выполняющих действие |Шаблоны относятся только к вашему тенанту и используются только по вашей инструкции внутри вашего приложения: для обнаружения дубликатов лиц и нескольких аккаунтов, для [Биометрической аутентификации](https://docs.didit.me/ru/core-technology/biometric-auth/overview.md) и для ваших собственных списков лиц. Они никогда не используются для обучения моделей, аналитики, сравнения между организациями, общих сигналов [Networks](https://docs.didit.me/ru/console/networks.md) или независимой обработки мошенничества со стороны Didit.## Объект шаблона```json theme={null}
{
  "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b",
  "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f",
  "vendor_data": "user-42",
  "source_type": "session_delete",
  "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f",
  "retention_policy": "retain_until_user_deleted",
  "retention_override": null,
  "retained_at": "2026-08-28T10:15:42.318402Z",
  "expires_at": "2027-08-28T10:15:42.318402Z",
  "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e",
  "retained_by_type": "API_KEY",
  "instruction_class": "operational_session_delete",
  "instruction_source": "api",
  "instruction_id": "post-approval-cleanup-2026-08",
  "held_out_of_use": false,
  "status": "active",
  "purged_at": null
}
```| Поле | Тип | Описание |
| - | - | - |
| `uuid` | UUID | Идентификатор шаблона. Генерируется случайным образом; не основан на удалённой сессии или изображении её лица. |
| `vendor_user_uuid` | UUID | Владелец-Пользователь. |
| `vendor_data` | string или null | Текущий `vendor_data` Пользователя, определяемый при чтении шаблона. |
| `source_type` | enum | `session_delete`, `automatic_retention` или `backfill`. |
| `provenance_reference` | UUID | Непрозрачная ссылка, которая связывает шаблон с его журналом аудита. Это не идентификатор удалённой сессии, и через API её нельзя сопоставить с сессией. |
| `retention_policy` | enum | Политика приложения на момент сохранения: `delete_with_session` или `retain_until_user_deleted`. |
| `retention_override` | boolean или null | Значение `retain_face_embeddings`, переданное при удалении, или `null`, если применялась политика. |
| `retained_at` | datetime | Когда был создан шаблон. |
| `expires_at` | datetime | Когда истекает срок действия шаблона и он автоматически удаляется. Всегда задано. |
| `retained_by` | string | Субъект, который дал инструкцию: идентификатор приложения для API-ключей, идентификатор участника Console для действий в Console или идентификатор `service:` для автоматического хранения. Никогда не адрес электронной почты. |
| `retained_by_type` | enum | `API_KEY`, `CONSOLE_USER` или `SYSTEM`. |
| `instruction_class` | enum | `operational_session_delete` или `privacy_erasure`. |
| `instruction_source` | enum | `api`, `console`, `automatic_retention`, `backfill`, `privacy_erasure`, `explicit_template_purge`, `vendor_user_delete`, `expiry`, `reconciliation`, `migration` или `system`. |
| `instruction_id` | string | `instruction_id`, который вы передали при удалении, или идентификатор, сгенерированный Didit, если вы его не передали. |
| `held_out_of_use` | boolean | `true` только пока действует режим юридического удержания. Шаблон, на который распространяется режим юридического удержания, исключается из всех сравнений. См. [Режим юридического удержания](#юридические-удержания). |
| `status` | enum | Статус жизненного цикла, см. ниже. |
| `purged_at` | datetime или null | Когда шаблон был удалён. |### Статус| `status` | Значение | Участвует в сравнении? |
| - | - | - |
| `pending` | Шаблон создаётся. Если удаление, которое его создало, вернуло `503`, повторите удаление, чтобы завершить создание. | Нет |
| `active` | Шаблон участвует в сравнении до `expires_at`. | Да, если `held_out_of_use` не равно `true` и срок `expires_at` ещё не истёк |
| `expired` | Срок `expires_at` истёк, выполняется автоматическое удаление. | Нет |
| `held_out_of_use` | Действует режим юридического удержания. | Нет |
| `purge_pending` | Выполняется удаление. | Нет |
| `purge_failed` | Удаление не удалось завершить, потому что хранилище биометрических данных было недоступно. Повторите удаление; до тех пор шаблон остаётся исключённым из сравнения. | Нет |
| `purged` | Шаблон удалён. Виден только в ответе на удаление как `already_purged`; удалённые шаблоны не выводятся в списке и при запросе по идентификатору возвращают `404`. | Нет |## Как шаблоны используются при сопоставленииАктивный шаблон (`active`) участвует в том же сопоставлении, что и живое лицо из сессии: автоматическое обнаружение дубликатов при новых сессиях, отдельный [API поиска по лицу](https://docs.didit.me/ru/standalone-apis/face-search.md), [Биометрическая аутентификация](https://docs.didit.me/ru/core-technology/biometric-auth/overview.md) и ваши списки лиц. Совпадение с сохранённым шаблоном передаётся с `source: "retained_template"`, а также с `vendor_user_id` и `vendor_data` пользователя-владельца и с `biometric_template_id`. Оно никогда не содержит id сессии, изображение совпадения, данные личности или статус, так как сессии, из которой было получено лицо, уже не существует. См. [отчёт «Поиск по лицу»](https://docs.didit.me/ru/core-technology/face-search/report-face-search.md).Сохранённый шаблон никогда не попадает в список блокировки. Если лицо удалённой сессии было в списке блокировки лиц, эта запись списка сохраняет собственную независимую биометрическую запись и собственный жизненный цикл: удаление записи из списка удаляет только запись блокировки, а удаление шаблона не затрагивает список.## Точки удаленияВсе перечисленные ниже случаи исключают шаблон из сопоставления и удаляют сохранённый шаблон:| Точка удаления | Способ |
| - | - |
| Явное удаление | [`DELETE /v3/biometric-templates/{uuid}/`](https://docs.didit.me/ru/management-api/biometric-templates/purge) или [`POST /v3/biometric-templates/delete/`](https://docs.didit.me/ru/management-api/biometric-templates/batch-purge), либо **Lists → Biometric templates** в Console |
| Удаление пользователя | [`POST /v3/users/delete/`](https://docs.didit.me/ru/management-api/users/delete) удаляет все шаблоны, привязанные к пользователю, до удаления самого пользователя |
| Удаление по требованию конфиденциальности | Любое удаление сессии этого пользователя, отправленное с `deletion_instruction: "privacy_erasure"`, удаляет все шаблоны, привязанные к пользователю, независимо от политики приложения |
| Истечение срока | Didit автоматически удаляет шаблон после истечения `expires_at` |Возврат политики приложения к `delete_with_session` прекращает создание новых шаблонов, но **не** удаляет существующие. Удалите их явно.Удаление сначала стирает сохранённый шаблон и только потом помечает его как удалённый. Поэтому, если удаление возвращает `503`, шаблон остаётся в статусе `purge_failed`, уже исключён из сопоставления и безопасен для повторного запроса. Повторное удаление уже удалённого шаблона возвращает `already_purged`.## Журнал аудитаЗаписывается каждая попытка сохранения и удаления, включая неудачные и неподходящие по условиям, с указанием действующего субъекта (`retained_by` / субъект удаления и его тип), `instruction_class`, `instruction_source`, `instruction_id`, `provenance_reference` и результата. Передавайте собственный `instruction_id` при удалениях, чтобы сопоставлять журнал аудита Didit с вашим журналом удаления данных. Записи аудита никогда не содержат изображений, векторов, полей личности или адресов электронной почты.## Юридические удержанияЮридическое удержание является исключением, а не режимом хранения. Didit не устанавливает удержания по собственной инициативе: удержание может быть установлено только по документированной инструкции в рамках вашего Соглашения об обработке данных или по обязательному предписанию компетентного органа. Пока удержание действует, шаблон помечается как `held_out_of_use`: он исключён из всех видов сопоставления и из обычного восстановления и никогда не участвует в поиске. API для создания или снятия удержаний не существует. Если вы получили предписание, которое затрагивает сохранённые шаблоны, свяжитесь с вашим представителем Didit.## Права доступа и аутентификацияEndpoints Biometric Templates принимают только API-ключи приложения (`x-api-key`). Токены пользователей Business Console отклоняются с кодом `403`. Пользователи Console управляют шаблонами через **Lists → Biometric templates**, имея разрешение `lists`.## Endpoints| Endpoint | Метод | Назначение |
| - | - | - |
| [`/v3/biometric-templates/`](https://docs.didit.me/ru/management-api/biometric-templates/list) | GET | Постраничный список с фильтрами |
| [`/v3/biometric-templates/count/`](https://docs.didit.me/ru/management-api/biometric-templates/count) | GET | Количество с теми же фильтрами |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/ru/management-api/biometric-templates/get) | GET | Один шаблон |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/ru/management-api/biometric-templates/purge) | DELETE | Удаление одного шаблона |
| [`/v3/biometric-templates/delete/`](https://docs.didit.me/ru/management-api/biometric-templates/batch-purge) | POST | Удаление по списку id или по фильтру |## Связанные материалы- [Удаление сессии](https://docs.didit.me/ru/sessions-api/delete-session.md)
- [Пакетное удаление сессий](https://docs.didit.me/ru/management-api/sessions/batch-delete.md)
- [Хранение данных](https://docs.didit.me/ru/console/data-retention.md#хранение-биометрических-шаблонов)
- [Лица и биометрия](https://docs.didit.me/ru/entities/users/faces-and-biometrics.md)


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