> ## 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/ko/core-technology/liveness/overview.md) 중에 얼굴을 캡처하고, 벡터 임베딩을 생성한 뒤, 이를 네 가지 후속 기능에 사용하기 위해 저장합니다: **1:N 얼굴 검색**, **중복 감지**, **차단 목록 적용**, **생체 재인증**.> [!NOTE]
>
> 저장된 얼굴은 [생체 인증](https://docs.didit.me/ko/core-technology/biometric-auth/overview.md)의 기준 얼굴로도 사용됩니다. 사용자의 `vendor_data`로 생체 인증 세션을 생성하고 `portrait_image`를 생략하면, Didit이 저장된 얼굴을 자동으로 사용합니다. 사용 순서는 승인된 라이브니스 얼굴, 전자여권 칩 사진, 신분증 문서의 초상 사진, 수동으로 등록된 프로필 얼굴 순입니다.## 얼굴이 사용자에 연결되는 방식**1. 라이브니스 중 캡처**라이브니스 감지가 활성화된 세션을 사용자가 진행하면, Didit은 셀피를 캡처하고 패시브 라이브니스 감지를 실행하며, 가장 큰 얼굴을 추출하고 검색용 벡터 임베딩을 생성합니다.**2. 사용자 프로필에 저장**얼굴은 세션 및 상위 User 엔터티에 연결됩니다. 얼굴 이미지 URL은 `portrait_image`로 사용자 프로필에 표시됩니다.**3. 검색용 인덱싱**임베딩이 검색 인덱스에 추가됩니다. 이후 세션에서는 이 인덱스를 대상으로 1:N 검색을 실행할 수 있습니다.## 얼굴 검색(1:N)얼굴 검색을 사용하면 이미지를 업로드하여 애플리케이션에 등록된 모든 얼굴과 비교하고, 해당 사용자를 찾을 수 있습니다.사용 사례:- 온보딩 시 **중복 감지**: 동일한 사람이 계정을 두 개 만드는 것을 방지합니다.
- **역방향 조회**: 사기 조사에서 CCTV 프레임이나 이미지에 나타난 사용자를 식별합니다.
- **재방문 고객 인식**: 재방문 고객에 대해 KYC를 생략합니다.워크플로에서 중복 감지가 활성화되어 있으면 새 세션 중에 얼굴 검색이 자동으로 실행됩니다. 독립형 API로도 제공됩니다.- `POST /v3/face-search/` - [독립형 얼굴 검색](https://docs.didit.me/ko/standalone-apis/face-search.md)## 중복 감지새로 등록되는 모든 얼굴은 기존에 등록된 얼굴과 비교하여 중복 여부를 확인할 수 있습니다. Didit은 각 얼굴에 `approved_duplicate_status`를 부여합니다.| 상태 | 의미 |
| - | - |
| `NOT_DUPLICATED` | 유사도 임계값을 넘는 일치 항목이 없음 |
| `DUPLICATED` | 얼굴이 이미 승인된 세션의 하나 이상의 얼굴과 일치함 |워크플로는 다음과 같이 구성할 수 있습니다.- 중복으로 표시된 세션을 자동으로 **거부**합니다.
- **검토용으로 표시**하여 사람 분석가에게 전달합니다.
- **경고만 표시**하고 허용하되 위험 태그를 추가합니다.콘솔에서 *Workflows → \[your workflow] → Face Match / Liveness → Duplicate detection*에 해당하는 항목으로 이를 설정합니다.## 얼굴 차단 목록세션을 거부해도 해당 얼굴이 차단 목록에 추가되지는 않습니다. 같은 얼굴로 들어오는 이후 세션을 거부하려면 직접 차단 목록에 추가해야 합니다. [차단 목록 페이지](https://docs.didit.me/ko/console/blocklist-users.md)에서 추가하거나 [Lists API](https://docs.didit.me/ko/management-api/lists/overview.md)를 사용할 수 있습니다. 이후 라이브니스 셀피가 해당 항목과 일치하는 새 세션은 자동으로 거부됩니다.## 가져온 얼굴을 사용자 프로필에 업로드다른 KYC 제공업체에서 이전하는 경우, 먼저 User를 생성한 뒤 신뢰할 수 있는 얼굴 이미지를 해당 프로필에 연결할 수 있습니다. User는 여전히 `vendor_data`로 식별되지만, 얼굴 업로드 엔드포인트는 대상을 명확히 하기 위해 Didit 내부 User ID(`didit_internal_id`)를 사용합니다.**1. User 생성 또는 조회**안정적인 `vendor_data`로 [`POST /v3/users/create/`](https://docs.didit.me/ko/management-api/users/create)를 호출합니다. User가 이미 있다면 `GET /v3/users/{vendor_data}/`를 호출합니다.**2. didit\_internal\_id 읽기**User 응답에는 `didit_internal_id`가 포함됩니다. 자체 시스템에서는 계속 `vendor_data`를 사용하고, `didit_internal_id`는 프로필 연결 엔드포인트에서만 사용합니다.**3. 얼굴 업로드**Base64로 인코딩된 얼굴 이미지와 함께 [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/ko/management-api/users/upload-face)를 호출합니다.```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` | 차단 목록에 아무것도 추가되지 않으며, 사용자는 `ACTIVE` 상태를 유지합니다 |
| 분석가가 콘솔에서 얼굴을 수동으로 차단 | 얼굴이 추가되며, 정책에 따라 사용자 상태가 업데이트됩니다 |
| Lists API를 통한 프로그래밍 방식 추가 | 얼굴 이미지를 얼굴 유형 차단 목록에 업로드합니다 |### 차단 목록에 얼굴 업로드프로그래밍 방식으로 얼굴을 기준으로 사용자를 차단하려면 전용 [목록에 얼굴 업로드](https://docs.didit.me/ko/management-api/lists/upload-face.md) 엔드포인트를 사용해 얼굴 이미지를 얼굴 유형 차단 목록에 업로드합니다. Didit은 생체 임베딩을 추출하여 일치하는 인덱스에 삽입합니다. 이후 라이브니스 셀피가 일치하는 세션은 자동으로 거부됩니다.> [!NOTE]
>
> 프로필 얼굴 업로드와 얼굴 차단 목록 업로드는 서로 다른 작업입니다. 신뢰할 수 있는 가져온 얼굴을 증거, 중복 감지, 얼굴 검색을 위해 User에 연결하려면 프로필 업로드를 사용하세요. 이후 일치하는 세션을 거부하려면 얼굴을 차단하는 용도로 [Lists API](https://docs.didit.me/ko/management-api/lists/overview.md)를 사용하세요.### 차단 목록에서 얼굴 제거콘솔에서 *Blocklist → Faces → row actions → Remove*를 선택하거나 [항목 삭제](https://docs.didit.me/ko/management-api/lists/delete-entry.md) 엔드포인트를 사용하세요.## 세션 삭제 후 보존되는 생체 인식 템플릿세션을 삭제하면 얼굴 이미지와 기본적으로 얼굴 임베딩이 삭제되므로, 해당 인물은 중복 감지와 얼굴 검색에서 제외됩니다. 승인 직후 세션을 삭제하면서도 재가입을 계속 탐지해야 한다면, 애플리케이션에서 [생체 인식 템플릿 보존](https://docs.didit.me/ko/console/data-retention.md#생체-인식-템플릿-보존)을 활성화하거나 삭제 호출에 `retain_face_embeddings: true`를 보내십시오.Didit은 평소와 같이 세션과 해당 세션의 모든 데이터를 삭제하고, 사용자에 연결된 별도로 관리되는 이미지 없는 얼굴 생체 템플릿 하나를 보관합니다:- 숫자형 얼굴 템플릿과 보존 메타데이터만 포함합니다. 얼굴 이미지, 라이브니스 영상, 문서 데이터, 추출된 신원 필드, 결정, 삭제된 세션의 ID는 절대 포함하지 않습니다.
- 라이브 세션의 얼굴과 똑같이 중복 감지, 얼굴 검색, 생체 인증, 얼굴 목록에 참여합니다. 일치 항목은 `source: "retained_template"`, 사용자의 `vendor_user_id`와 `vendor_data`, 그리고 `biometric_template_id`와 함께 보고됩니다.
- 생체 데이터이며 만료 시점이 `expires_at`으로 설정되어 있습니다. 사용자가 삭제되거나, 해당 사용자의 세션이 `deletion_instruction: "privacy_erasure"`와 함께 삭제되거나, 만료되거나, **Lists → Biometric templates**에서 또는 [Biometric Templates API](https://docs.didit.me/ko/management-api/biometric-templates/overview.md)를 통해 직접 파기할 때 파기됩니다.
- `vendor_data` 없이 생성된 세션에는 템플릿을 연결할 사용자가 없습니다. 이 세션을 삭제하면 `ineligible_no_vendor_user`가 보고되고, 임베딩은 세션과 함께 삭제됩니다.
- 보존된 템플릿은 차단 목록에 등록되지 않습니다. 삭제된 세션에서 생성된 얼굴 차단 목록 항목은 자체적인 독립 생체 항목과 수명 주기를 유지합니다.사용자에 연결된 템플릿은 사용자 프로필의 **Biometric templates** 아래에 표시되며, 파기 작업이 함께 제공됩니다.## 얼굴 수명 주기 요약```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) 얼굴은 프로필 증빙, 중복 감지, 얼굴 검색을 위해 등록됩니다. 향후 일치하는 세션을 거부하는 것이 목적이라면 Blocklist 영역을 사용하십시오.다음과 같은 경우에 유용합니다:- 오프라인 채널로 확인된 고객의 알려진 초상 사진이 있는 경우.
- 사기 데이터베이스의 알려진 악성 행위자를 차단 목록에 미리 등록하려는 경우.## 개인정보 보호 및 보존- 얼굴 임베딩은 이미지가 아닌 수치 벡터입니다. 이미지 자체는 서명된 URL을 통해 액세스할 수 있는 암호화된 객체 스토리지에 저장됩니다. 얼굴 임베딩은 생체 데이터입니다.
- 보존 기간은 애플리케이션의 [데이터 보존](https://docs.didit.me/ko/console/data-retention.md) 정책을 따릅니다. 보존된 생체 인식 템플릿은 더 엄격하고 유한한 [생체 인식 템플릿 보존](https://docs.didit.me/ko/console/data-retention.md#생체-인식-템플릿-보존) 기간을 따릅니다.
- 세션을 삭제하면 이미지와 기본적으로 임베딩이 삭제됩니다. 애플리케이션에서 생체 인식 템플릿 보존을 사용하도록 설정한 경우, 세션을 삭제해도 이미지 없는 템플릿은 만료되거나 파기될 때까지 유지됩니다.
- GDPR / CCPA 잊힐 권리 요청의 경우, `deletion_instruction: "privacy_erasure"`를 지정하여 해당 인물의 세션을 삭제하거나 사용자를 삭제하십시오. 두 방법 모두 보존된 모든 템플릿도 함께 파기합니다. 관리하는 얼굴 차단 목록 항목은 직접 제거하기 전까지 유지됩니다.## 다음 단계> [card] [얼굴 검색](https://docs.didit.me/ko/core-technology/face-search/overview.md)
>
> 1:N 얼굴 검색의 작동 방식입니다.> [card] [라이브니스](https://docs.didit.me/ko/core-technology/liveness/overview.md)
>
> 얼굴을 포착하는 라이브니스 감지입니다.> [card] [차단 목록 API](https://docs.didit.me/ko/management-api/lists/upload-face.md)
>
> 차단 목록에 얼굴을 업로드합니다.> [card] [생체 인식 템플릿](https://docs.didit.me/ko/management-api/biometric-templates/overview.md)
>
> 세션 삭제 후 보존되는 템플릿입니다.> [card] [사용자 차단 목록](https://docs.didit.me/ko/entities/users/blocklist.md)
>
> 사용자를 차단 목록에 등록하는 방식입니다.


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