생체 인식 템플릿 API

기본적으로 세션을 삭제하면 해당 세션에서 얼굴 검색 1:N과 중복 감지를 지원하던 얼굴 임베딩도 함께 삭제됩니다. 세션 삭제 후에도 중복 감지가 계속 작동해야 하는 애플리케이션은 생체 인식 템플릿 보존을 선택할 수 있습니다. 이 경우 Didit은 세션과 해당 세션의 모든 데이터를 평소와 같이 삭제하되, 세션의 사용자에 연결된 이미지 없는 얼굴 생체 인식 템플릿 하나를 별도로 관리하며 보관합니다. Biometric Templates API를 사용하면 애플리케이션이 어떤 템플릿을 보유하고 있는지, 그 이유가 무엇인지, 언제까지 보관되는지 확인할 수 있으며, 언제든지 템플릿을 삭제할 수 있습니다. 모든 템플릿은 Business Console의 Lists → Biometric templates와 해당 사용자의 프로필에서도 확인할 수 있습니다.

보존된 생체 인식 템플릿은 생체 데이터입니다. 익명 데이터가 아니며, 일시적인 데이터도 아니고, 세션과 함께 삭제되지도 않습니다. 템플릿은 예정된 만료일, 더 이른 적용 법령의 기한, 사용자 삭제, 개인정보 삭제 요청 또는 명시적 삭제가 있을 때까지 유지됩니다. 개인정보처리자의 지시와 개인정보 처리방침이 이를 포함하는 경우에만 보존을 활성화하십시오.

템플릿 생성 방식

트리거	`source_type`	지시의 출처
보존이 활성화된 애플리케이션에서 세션을 삭제하거나, Delete Session 또는 Batch Delete Sessions에 `retain_face_embeddings: true`를 보냅니다	`session_delete`	`instruction_source: api` 또는 `console`
보존이 활성화된 애플리케이션의 일반 데이터 보존 기간이 만료되어 세션이 만료됩니다	`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`	행위자의 이메일 주소

템플릿은 테넌트 범위로 관리되며, 애플리케이션 내에서 애플리케이션의 지시에 따라서만 사용됩니다. 여기에는 중복 얼굴 및 다중 계정 감지, 생체 인증, 그리고 애플리케이션의 자체 얼굴 목록이 포함됩니다. 템플릿은 모델 학습, 분석, 기관 간 매칭, 네트워크 공유 신호 또는 Didit의 독립적인 사기 처리에는 절대 사용되지 않습니다.

템플릿 객체

{
  "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, 생체 인증, 그리고 얼굴 목록이 여기에 해당합니다. 보존된 템플릿에 대한 적중은 source: "retained_template", 소유한 사용자의 vendor_user_id와 vendor_data, 그리고 biometric_template_id와 함께 보고됩니다. 얼굴을 생성한 세션이 더 이상 존재하지 않으므로 세션 ID, 매칭 이미지, 신원 정보, 상태는 포함되지 않습니다. 자세한 내용은 얼굴 검색 보고서를 참조하세요. 보존된 템플릿은 차단 목록에 등록되지 않습니다. 삭제된 세션의 얼굴이 얼굴 차단 목록에 있었다면, 해당 차단 목록 항목은 별도의 생체 항목과 독립적인 수명 주기를 유지합니다. 목록 항목을 제거하면 차단 목록 항목이 삭제되며, 템플릿을 퍼지해도 목록에는 영향을 주지 않습니다.

퍼지 시점

아래 모든 경우에 템플릿이 매칭에서 제외되고 저장된 템플릿이 삭제됩니다.

퍼지 시점	방법
명시적 퍼지	`DELETE /v3/biometric-templates/{uuid}/` 또는 `POST /v3/biometric-templates/delete/`, 또는 Console의 Lists → Biometric templates
사용자 삭제	`POST /v3/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/`	GET	필터가 적용된 페이지네이션 목록
`/v3/biometric-templates/count/`	GET	동일한 필터로 개수 조회
`/v3/biometric-templates/{template_uuid}/`	GET	템플릿 하나 조회
`/v3/biometric-templates/{template_uuid}/`	DELETE	템플릿 하나 퍼지
`/v3/biometric-templates/delete/`	POST	ID 목록 또는 필터로 퍼지

​템플릿 생성 방식

​템플릿에 포함되는 내용

​템플릿 객체

​상태

​매칭에서 템플릿이 사용되는 방식

​퍼지 시점

​감사 추적

​법적 보류

​권한 및 인증

​엔드포인트

​관련 문서

템플릿 생성 방식

템플릿에 포함되는 내용

템플릿 객체

상태

매칭에서 템플릿이 사용되는 방식

퍼지 시점

감사 추적

법적 보류

권한 및 인증

엔드포인트

관련 문서