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

> Didit에서 세션 삭제 후에도 보관되는 이미지 없는 얼굴 생체 인식 템플릿을 API로 목록 조회, 개수 확인, 필터링, 상세 확인, 삭제할 수 있습니다.



Biometric Templates 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/ko/core-technology/face-search/overview.md)과 중복 감지를 지원하던 얼굴 임베딩도 함께 삭제됩니다. 세션 삭제 후에도 중복 감지가 계속 작동해야 하는 애플리케이션은 **생체 인식 템플릿 보존**을 선택할 수 있습니다. 이 경우 Didit은 세션과 해당 세션의 모든 데이터를 평소와 같이 삭제하되, 세션의 [사용자](https://docs.didit.me/ko/entities/users/overview.md)에 연결된 이미지 없는 얼굴 생체 인식 템플릿 하나를 별도로 관리하며 보관합니다.Biometric Templates API를 사용하면 애플리케이션이 어떤 템플릿을 보유하고 있는지, 그 이유가 무엇인지, 언제까지 보관되는지 확인할 수 있으며, 언제든지 템플릿을 삭제할 수 있습니다. 모든 템플릿은 Business Console의 **Lists → Biometric templates**와 해당 사용자의 프로필에서도 확인할 수 있습니다.> [!WARNING]
>
> 보존된 생체 인식 템플릿은 생체 데이터입니다. 익명 데이터가 아니며, 일시적인 데이터도 아니고, 세션과 함께 삭제되지도 않습니다. 템플릿은 예정된 만료일, 더 이른 적용 법령의 기한, 사용자 삭제, 개인정보 삭제 요청 또는 명시적 삭제가 있을 때까지 유지됩니다. 개인정보처리자의 지시와 개인정보 처리방침이 이를 포함하는 경우에만 보존을 활성화하십시오.## 템플릿 생성 방식| 트리거 | `source_type` | 지시의 출처 |
| - | - | - |
| 보존이 활성화된 애플리케이션에서 세션을 삭제하거나, [Delete Session](https://docs.didit.me/ko/sessions-api/delete-session.md) 또는 [Batch Delete Sessions](https://docs.didit.me/ko/management-api/sessions/batch-delete.md)에 `retain_face_embeddings: true`를 보냅니다 | `session_delete` | `instruction_source: api` 또는 `console` |
| 보존이 활성화된 애플리케이션의 일반 [데이터 보존 기간](https://docs.didit.me/ko/console/data-retention.md)이 만료되어 세션이 만료됩니다 | `automatic_retention` | `instruction_source: automatic_retention` |
| 보존 기능을 켜기 전에 삭제된 세션에 대해 지시한 Didit 운영 백필 | `backfill` | `instruction_source: backfill` |보존에는 사용자 연결이 필요합니다. `vendor_data` 없이 생성된 세션에는 사용자가 없으므로 템플릿을 보존할 수 없습니다. 이 경우 삭제 결과는 `ineligible_no_vendor_user`로 보고되며, 임베딩은 세션과 함께 삭제됩니다.## 템플릿에 포함되는 내용| 보존되는 항목 | 절대 보존되지 않는 항목 |
| - | - |
| 매칭에 사용되는 숫자 형식의 얼굴 템플릿 | 얼굴 이미지, 라이브니스 영상, 문서 이미지, 인물 이미지 크롭 및 기타 모든 미디어 |
| 새로 생성된 무작위 템플릿 `uuid`와 불투명한 `provenance_reference` | 삭제된 세션의 ID, 번호, 결정, 추출된 신원 필드 또는 기능 페이로드 |
| 소유 사용자(`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/ko/core-technology/biometric-auth/overview.md), 그리고 애플리케이션의 자체 얼굴 목록이 포함됩니다. 템플릿은 모델 학습, 분석, 기관 간 매칭, [네트워크](https://docs.didit.me/ko/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 | 템플릿 ID입니다. 무작위로 생성되며, 삭제된 세션이나 얼굴에서 파생되지 않습니다. |
| `vendor_user_uuid` | UUID | 소유 사용자입니다. |
| `vendor_data` | string 또는 null | 템플릿을 조회할 때 확인되는 사용자의 현재 `vendor_data`입니다. |
| `source_type` | enum | `session_delete`, `automatic_retention` 또는 `backfill`입니다. |
| `provenance_reference` | UUID | 템플릿을 감사 로그와 연결하는 불투명한 참조입니다. 삭제된 세션의 ID가 아니며, API를 통해 세션 ID로 해석할 수 없습니다. |
| `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 키의 경우 애플리케이션 ID, Console 작업의 경우 Console 멤버 ID, 자동 보존의 경우 `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이 생성한 ID입니다. |
| `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/ko/standalone-apis/face-search.md), [생체 인증](https://docs.didit.me/ko/core-technology/biometric-auth/overview.md), 그리고 얼굴 목록이 여기에 해당합니다. 보존된 템플릿에 대한 적중은 `source: "retained_template"`, 소유한 사용자의 `vendor_user_id`와 `vendor_data`, 그리고 `biometric_template_id`와 함께 보고됩니다. 얼굴을 생성한 세션이 더 이상 존재하지 않으므로 세션 ID, 매칭 이미지, 신원 정보, 상태는 포함되지 않습니다. 자세한 내용은 [얼굴 검색 보고서](https://docs.didit.me/ko/core-technology/face-search/report-face-search.md)를 참조하세요.보존된 템플릿은 차단 목록에 등록되지 않습니다. 삭제된 세션의 얼굴이 얼굴 차단 목록에 있었다면, 해당 차단 목록 항목은 별도의 생체 항목과 독립적인 수명 주기를 유지합니다. 목록 항목을 제거하면 차단 목록 항목이 삭제되며, 템플릿을 퍼지해도 목록에는 영향을 주지 않습니다.## 퍼지 시점아래 모든 경우에 템플릿이 매칭에서 제외되고 저장된 템플릿이 삭제됩니다.| 퍼지 시점 | 방법 |
| - | - |
| 명시적 퍼지 | [`DELETE /v3/biometric-templates/{uuid}/`](https://docs.didit.me/ko/management-api/biometric-templates/purge) 또는 [`POST /v3/biometric-templates/delete/`](https://docs.didit.me/ko/management-api/biometric-templates/batch-purge), 또는 Console의 **Lists → Biometric templates** |
| 사용자 삭제 | [`POST /v3/users/delete/`](https://docs.didit.me/ko/management-api/users/delete)는 사용자를 삭제하기 전에 해당 사용자에 연결된 모든 템플릿을 퍼지합니다 |
| 개인정보 삭제 | `deletion_instruction: "privacy_erasure"`와 함께 전송된 해당 사용자의 세션 삭제는 애플리케이션 정책과 관계없이 해당 사용자에 연결된 모든 템플릿을 퍼지합니다 |
| 만료 | `expires_at`이 지나면 Didit이 템플릿을 자동으로 퍼지합니다 |애플리케이션 정책을 `delete_with_session`으로 되돌리면 새 템플릿 생성은 중단되지만 기존 템플릿은 **퍼지되지 않습니다**. 기존 템플릿은 명시적으로 퍼지해야 합니다.퍼지는 먼저 저장된 템플릿을 삭제한 다음에만 템플릿을 퍼지된 것으로 표시합니다. 따라서 퍼지가 `503`을 반환하면 템플릿은 `purge_failed` 상태로 남고, 이미 매칭에서 제외된 상태이며, 안전하게 다시 시도할 수 있습니다. 이미 퍼지된 템플릿에 대해 다시 퍼지를 요청하면 `already_purged`가 반환됩니다.## 감사 추적모든 보존 및 퍼지 시도는 실패와 자격 미달 결과를 포함하여 실행 주체(`retained_by` / 퍼지 실행 주체 및 유형), `instruction_class`, `instruction_source`, `instruction_id`, `provenance_reference`, 그리고 결과와 함께 기록됩니다. 삭제 요청에는 Didit의 감사 추적을 귀사의 삭제 로그와 대조할 수 있도록 직접 `instruction_id`를 보내세요. 감사 항목에는 이미지, 벡터, 신원 필드, 이메일 주소가 포함되지 않습니다.## 법적 보류법적 보류는 예외 사항이며 보존 모드가 아닙니다. Didit은 자체 판단으로 보류를 설정하지 않습니다. 보류는 귀사의 데이터 처리 계약에 따른 문서화된 지시나 권한 있는 기관의 구속력 있는 명령에 따라서만 설정될 수 있습니다. 보류가 적용되는 동안 템플릿은 `held_out_of_use`로 표시되며, 모든 유형의 매칭과 일상적인 복구에서 제외되고 검색할 수 없습니다. 보류를 생성하거나 해제하는 API는 없습니다. 보존된 템플릿에 영향을 미치는 명령을 받으셨다면 Didit 담당자에게 문의하세요.## 권한 및 인증생체 인식 템플릿 엔드포인트는 애플리케이션 API 키(`x-api-key`)만 허용합니다. Business Console 사용자 토큰은 `403`으로 거부됩니다. Console 사용자는 `lists` 권한을 가지고 **Lists → Biometric templates**에서 템플릿을 관리합니다.## 엔드포인트| 엔드포인트 | 메서드 | 용도 |
| - | - | - |
| [`/v3/biometric-templates/`](https://docs.didit.me/ko/management-api/biometric-templates/list) | GET | 필터가 적용된 페이지네이션 목록 |
| [`/v3/biometric-templates/count/`](https://docs.didit.me/ko/management-api/biometric-templates/count) | GET | 동일한 필터로 개수 조회 |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/ko/management-api/biometric-templates/get) | GET | 템플릿 하나 조회 |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/ko/management-api/biometric-templates/purge) | DELETE | 템플릿 하나 퍼지 |
| [`/v3/biometric-templates/delete/`](https://docs.didit.me/ko/management-api/biometric-templates/batch-purge) | POST | ID 목록 또는 필터로 퍼지 |## 관련 문서- [세션 삭제](https://docs.didit.me/ko/sessions-api/delete-session.md)
- [세션 일괄 삭제](https://docs.didit.me/ko/management-api/sessions/batch-delete.md)
- [데이터 보존](https://docs.didit.me/ko/console/data-retention.md#생체-인식-템플릿-보존)
- [얼굴 및 생체 인식](https://docs.didit.me/ko/entities/users/faces-and-biometrics.md)


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