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

# 얼굴 검색 1:N API: 중복 감지

> Didit의 얼굴 검색으로 인증된 전체 사용자 중 중복 계정 및 차단 목록 등록자를 2초 이내에 감지하세요. Didit 신원 인증 시 무료로 제공됩니다.

얼굴 검색은 승인된 모든 신분증 인증 세션에서 특정 얼굴을 검색할 수 있는 강력한 기능입니다. 이 기능을 통해 중복 계정을 식별하고 사기를 방지하며 보안 조치를 강화할 수 있습니다.

얼굴 검색 연동 프롬프트
        프롬프트를 클립보드에 복사



      
      

\<pre>

\````# Goal
Integrate Didit Face Search (1:N — search a face across your enrolled users + blocklist) into your app.

\# Delivery mode
Face Search is a **standalone API**. It runs against the face index your application has enrolled through prior verifications (sessions with save_api_request=true or Passive Liveness with save_api_request=true), faces uploaded to User profiles, your face lists, and any image-free biometric templates the application retained after deleting sessions (opt-in, see /management-api/biometric-templates/overview). There is no separate Face Search workflow feature.

POST https://verification.didit.me/v3/face-search/
multipart/form-data — x-api-key: YOUR_API_KEY

Required: `user_image` (jpg/jpeg/png/tiff/webp, max 5 MB; PDFs not accepted). The image must contain at least one detectable face (largest bbox wins when multiple).

Optional: `search_type` = "most_similar" (default — dedupe / returning-user) | "blocklisted_or_approved" (blocklist screening).

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-search/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'search_type=most_similar' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```

\# Response shape (singular)
Unlike most features, Face Search returns a **singular** `face_search` object — not a plural array:
\{ request_id, face_search: { status, total_matches, matches: [{ session_id, session_number, similarity_percentage, source, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details, match_image_url, status, is_blocklisted, is_allowlisted, api_service }], user_image: {entities}, warnings: [...] } }

match.source is "session", "imported", "list_entry", or "retained_template". A retained_template hit comes from an image-free biometric template kept after the source session was deleted: session_id, session_number, status, api_service, match_image_url, and user_details are null; vendor_data and vendor_user_id identify the User; biometric_template_id is the template you can inspect or purge via /v3/biometric-templates/{id}/.

\`status` is "Declined" only when at least one blocklist match is found. Pure duplicate matches return "Approved" (informational) — apply your own dedupe policy in app logic.

\# Warnings
Face Search emits risk codes from the LogWarningChoices.FACEMATCH bucket plus blocklist/duplicate semantics:
FACE_IN_BLOCKLIST, POSSIBLE_FACE_IN_BLOCKLIST, DUPLICATED_FACE, POSSIBLE_DUPLICATED_FACE, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-search/warnings-face-search.

\# Failure modes to handle
\- HTTP 400 — no face detected in user_image. Ask the user to retake.
\- HTTP 403 — out of credits.
\- status="Declined" with FACE_IN_BLOCKLIST — definitive blocklist hit; reject.
\- POSSIBLE_FACE_IN_BLOCKLIST — borderline match below the hard threshold; route to manual review.
\- DUPLICATED_FACE — user already verified under a different vendor_data; merge or block according to policy.

\# See also
\- Canonical schema: /reference/data-models#face-search
\- Per-feature report: /core-technology/face-search/report-face-search
\- Risk catalogue: /core-technology/face-search/warnings-face-search
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

붙여넣을 곳

인증 결과를 확인하는 방법에 대한 Academy 강의의 6:53 구간에서 얼굴 검색과 차단 목록을 다룹니다.[얼굴 검색 및 차단 목록 — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=413\&rel=0\&playsinline=1)![중복 및 차단 목록 감지를 위해 라이브니스와 연동된 Didit 얼굴 검색 1:N 플로우](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/face-search-liveness.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=0cb5738f8ceaae7891cf13631485c400)## 자동 얼굴 검색 연동> 얼굴 검색은 인증 세션의 라이브니스 확인 과정에서 자동으로 수행되어 중복 사용자를 감지하고 차단 목록에 등록된 얼굴과 대조합니다.### 자동 중복 감지사용자가 신분증 인증 중 라이브니스 확인을 완료하면 다음과 같이 처리됩니다.- 사용자의 안면 생체 정보가 이전에 인증된 모든 사용자와 자동으로 비교됩니다.
- 시스템이 안면 유사도를 기반으로 잠재적인 중복 계정을 식별합니다.
- 구성된 유사도 임계값에 따라 일치 항목이 표시됩니다.
- 잠재적인 중복 사용자를 검토하고 이에 대한 작업을 수행할 수 있습니다.### 차단 목록 연동얼굴 검색은 [차단 목록 기능](https://docs.didit.me/ko/management-api/lists/overview.md)과 매끄럽게 연동됩니다.- 인증 중 얼굴이 차단 목록과 자동으로 대조됩니다.
- 차단 목록에 등록된 얼굴과 일치하는 항목이 발견되면 인증이 자동으로 거부됩니다.
- 이를 통해 이전에 문제가 확인된 사용자가 새 계정을 생성하는 것을 방지합니다.
- 인증 프로세스의 무결성을 유지하는 데 도움이 됩니다.### 문서 촬영 중 캡처된 셀피사용자가 문서를 촬영하는 동안 전면 카메라가 사용자의 셀피를 촬영합니다(Silent Capture). 문서가 평가될 때마다 해당 셀피는 라이브니스 셀피와 동일한 1:N 검색을 거치게 됩니다.- 라이브니스 검색과 동일한 유사도 임계값 및 우선순위를 적용하여 얼굴 차단 목록 및 애플리케이션에서 이미 승인된 사용자와 비교됩니다.
- 차단 목록 일치 시 `FRONT_CAMERA_FACE_IN_BLOCKLIST`(항상 거부됨) 또는 `POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST`(항상 검토) 경고가 발생합니다. 승인된 사용자와 일치 시 `FRONT_CAMERA_DUPLICATED_FACE` 또는 `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE`가 발생하며, 해당 승인된 사용자가 다른 이름으로 인증된 경우 `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH`, 해당 사용자의 신분증에 다른 생년월일이 표시되어 있는 경우 `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH`가 추가로 발생합니다. 자세한 내용은 [신분증 인증 경고](https://docs.didit.me/ko/core-technology/id-verification/warnings-id-verification.md)를 참고하십시오.
- 일치 항목은 세션 상세 정보의 신분증 인증 카드에 나열되며, [세션 결정](https://docs.didit.me/ko/sessions-api/retrieve-session.md)의 `id_verifications[].document_selfie_face_matches`에 반환됩니다. `liveness_checks[].matches`와 동일한 엔트리 형식을 사용합니다. 이전 세션이거나 검색이 실행되지 않은 경우 이 필드는 `null`이며, 실행되었으나 일치 항목을 찾지 못한 경우에는 빈 배열이 됩니다. `match_image_url`은 만료 시간이 있는 사전 서명된 URL입니다.
- 셀피에서 가장 큰 얼굴만 사용되며, 감지기가 얼굴임을 확신할 때만 사용됩니다. 문서당 하나의 셀피만 검색됩니다. 앞면 셀피가 검색되며, 앞면 셀피에 명확한 얼굴이 없는 경우 뒷면 셀피가 검색됩니다.
- 해당 셀피는 비교에만 사용됩니다. 생체 인식 템플릿은 저장되지 않으므로 이후 세션에서 이 셀피와 대조되지 않습니다. 세션의 셀피를 기준으로 특정 인물을 차단하려면 세션 페이지에서 해당 인물을 얼굴 차단 목록에 추가하십시오.이 검색에는 **신분증 인증** 단계의 **규칙** 탭(**Silent Capture 얼굴 검색**) 또는 [워크플로 기능 설정](https://docs.didit.me/ko/management-api/workflows/feature-configs.md#ocr-/-신분증-인증)의 `document_selfie_face_search_enabled` 및 `document_selfie_duplicated_face_*` 작업을 통해 제어할 수 있는 자체 스위치와 작업이 있습니다. 기본적으로 활성화되어 있습니다. 중복 얼굴 작업의 기본값은 승인(경고는 계속 보고됨)이며, 이름 및 문서 교차 확인의 기본값은 라이브니스와 마찬가지로 검토입니다. 검색에는 셀피가 필요하므로 Silent Capture가 켜져 있을 때만 실행됩니다. 라이브니스 감지 단계에서 얼굴 검색을 끄면 이 검색도 함께 꺼집니다. 이 비활성화는 해당 인물의 얼굴에 적용되는 설정이므로 세션의 모든 셀피에 적용됩니다.### 문서 불일치 규칙**문서 불일치** 규칙(라이브니스 셀피의 경우 `DUPLICATED_FACE_DOCUMENT_MISMATCH`, Silent Capture의 경우 `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH`)은 일치한 사용자의 신분증에 다른 생년월일이 표시된 경우에만 중복된 얼굴로 플래그를 지정합니다.
동일한 인물이 다른 문서(예: 신분증 제시 후 여권 제시)를 제출하는 경우에는 플래그가 지정되지 않습니다.
갱신된 문서 역시 플래그가 지정되지 않습니다.
동일한 국가에서 동일한 문서 번호를 사용하는 두 세션은 절대 플래그가 지정되지 않습니다.### 자동 얼굴 검색 끄기자동 얼굴 검색은 모든 라이브니스 감지 단계에서 기본적으로 활성화되어 있습니다. 개인정보 보호 정책상 필요한 경우, Business Console(단순 및 고급 모드)의 **라이브니스 감지** 단계의 **규칙** 탭에서 워크플로별로 비활성화하거나 [워크플로 기능 설정](https://docs.didit.me/ko/management-api/workflows/feature-configs.md#라이브니스-감지)의 `LIVENESS` 또는 `AGE_ESTIMATION` 노드에서 `face_search_enabled: false`로 설정하여 비활성화할 수 있습니다.스위치를 끄더라도 라이브니스 셀피에 대해 라이브니스 점수 산정 및 얼굴 대조를 통한 문서 사진과의 1:1 비교는 계속 수행되지만, 얼굴 색인에는 절대 도달하지 않습니다.- 검색이 실행되지 않으므로 세션에 중복, 차단 목록 또는 허용 목록 판정이 내려지지 않으며 `liveness_checks[].matches`는 빈 상태로 유지됩니다. **중복된 얼굴**, **이름 불일치**, **문서 불일치** 및 교차 조직 얼굴 규칙은 적용할 대상이 없으므로 콘솔에서 숨겨집니다.
- 셀피에 대한 생체 인식 템플릿이 저장되지 않으므로 이후 세션이 이 세션과 일치할 수 없으며, 세션이 삭제된 후 [생체 인식 템플릿 보존](https://docs.didit.me/ko/console/data-retention.md#생체-인식-템플릿-보존)을 통해 유지할 대상도 없습니다.
- 셀피는 교차 조직 확인을 위해 공유 생체 인식 인물을 식별하는 데 사용되지 않습니다.
- 문서 촬영 중에 캡처된 셀피 역시 검색되지 않습니다(`FRONT_CAMERA_*` 차단 목록 또는 중복 위험 없음). 비활성화 설정이 세션의 모든 셀피에 적용되기 때문입니다. 신분증 인증 단계 자체의 스위치(위 참조)를 통해 해당 검색만 별도로 끌 수도 있습니다.**스위치가 속한 단계.** 스위치는 셀피를 캡처하는 단계에 위치하므로, **라이브니스 감지** 또는 **연령 추정** 단계가 자체적으로 이를 처리합니다. **얼굴 대조** 단계에는 자체 스위치가 없습니다. 사용자가 해당 단계에서 셀피를 다시 촬영하는 경우(예: 해당 단계를 다시 제출하도록 요청한 후) 재촬영은 라이브니스 감지 단계의 설정을 따르므로, 비활성화되어 있다면 새 셀피 역시 색인에서 제외됩니다. 워크플로가 둘 이상의 라이브니스 감지 단계로 분기되는 경우 세션이 실제로 거친 분기의 설정이 적용되며, 교차 조직 얼굴 확인도 동일한 단계의 설정을 따릅니다.기존 워크플로는 사용자가 비활성화하기 전까지 현재의 동작 방식을 유지합니다. 변경 사항은 워크플로를 저장한 후 시작된 세션에 적용되며, 이전 세션에서 저장된 템플릿은 해당 세션이 삭제되거나 제거(purge)될 때까지 색인에 유지됩니다. 이 스위치는 직접 명시적으로 호출하는 독립형 [Face Search API](https://docs.didit.me/ko/standalone-apis/face-search.md)에는 영향을 주지 않습니다.> [!WARNING]
>
> 얼굴 차단 목록은 인증 과정에서 동일한 1:N 검색을 통해 적용됩니다. 라이브니스 단계에서 얼굴 검색이 꺼져 있으면 차단 목록에 등록된 인물이 해당 단계와 문서 캡처 중에 촬영된 셀피 모두에서 감지되지 않으며, 신분증 인증 단계에서 Silent Capture Face Search가 꺼져 있으면 해당 셀피에서 감지되지 않습니다.### API 액세스얼굴 검색 기능은 [API](https://docs.didit.me/ko/standalone-apis/face-search.md)를 통해서도 제공되며, 다음 작업이 가능합니다:- 프로그래밍 방식으로 얼굴 검색 요청 전송
- 자체 애플리케이션에 얼굴 대조 기능 연동
- 맞춤형 사기 감지 워크플로 구축
- 중복 감지를 위한 자동화 시스템 구축## 주요 기능- **높은 정확도**: 고급 생체 인식 알고리즘을 통해 신뢰할 수 있는 일치 결과를 제공합니다.
- **구성 가능한 임계값**: 조직의 위험 허용 범위에 맞게 일치 민감도를 맞춤 설정할 수 있습니다.
- **포괄적인 스캔**: 인증된 모든 사용자를 대상으로 검색을 수행합니다.
- **신속한 결과**: 대규모 사용자 데이터베이스에서도 검색을 빠르게 처리합니다.
- **개인정보 보호 중심**: 애플리케이션 범위 내의 숫자형 얼굴 템플릿을 사용하여 대조를 수행하며, 색인은 테넌트 외부로 절대 유출되지 않습니다.### 구성 가능한 임계값유사도 점수에 대해 서로 다른 임계값을 설정하여 검색 민감도를 맞춤 설정할 수 있습니다:> [!NOTE]
>
> 이러한 임계값은 위험 허용 범위 및 보안 요구사항에 따라 조정할 수 있습니다.## 작동 방식**1. 얼굴 추출**검색이 시작되면 시스템이 기준 이미지를 처리합니다:| 프로세스 | 설명 |
| - | - |
| **특징 추출** | 기준 이미지에서 얼굴 특징을 분리합니다 |
| **정규화** | 일관된 비교를 위해 얼굴 데이터를 표준화합니다 |
| **품질 검증** | 이미지 품질과 얼굴 선명도를 확인합니다 |
| **벡터 인코딩** | 얼굴을 수학적 벡터 표현으로 변환합니다 |**2. 비교 알고리즘**시스템이 인증된 세션의 전체 데이터베이스를 검색합니다:- 기준 얼굴 벡터를 **애플리케이션에 등록된 모든 얼굴**(세션 얼굴, 사용자 프로필에 업로드된 얼굴, 얼굴 목록, 보존된 생체 인식 템플릿)과 비교합니다.
- 속도와 정확도에 최적화된 고급 신경망 아키텍처를 사용합니다.
- **가장 유사한 항목**(순위별 목록) 및 **차단 목록에 등록됨 또는 승인됨**(상태 필터링)의 두 가지 검색 모드를 지원합니다.
- 최적화된 인덱싱을 활용하여 대규모 데이터베이스를 빠르게 처리합니다.**3. 유사도 점수 산출**각 비교에 대해 유사도 백분율이 생성됩니다:| 점수 범위 | 해석 |
| :-: | - |
| **90%+** | 강력한 일치 — 동일 인물일 가능성이 매우 높음 |
| **70–89%** | 일치 가능성 있음 — 수동 검토가 필요할 수 있음 |
| **70% 미만** | 다른 개인일 가능성이 높음 |설정된 일치 임계값에 따라 플래그가 지정될 결과가 결정됩니다.**4. 결과 전송**시스템이 포괄적인 결과 집합을 반환합니다:- 유사도 점수 순으로 정렬된 잠재적 일치 항목의 **순위별 목록**
- 세션 ID, 인증 날짜, 벤더 데이터를 포함한 **일치 세부 정보**
- 각 일치 항목에 대한 **유사도 백분율**
- 시각적 검토에 사용할 수 있는 **일치 이미지**
- 일치한 얼굴의 차단 목록 등록 여부를 나타내는 **차단 목록 상태**## 삭제된 세션 및 보존된 생체 인식 템플릿기본적으로 세션을 삭제하면 해당 얼굴 임베딩도 삭제되므로 해당 인물은 색인에서 제외되어 중복 플래그 없이 다시 인증을 진행할 수 있습니다. 승인 직후 세션을 삭제하지만 반복 가입을 여전히 감지해야 하는 애플리케이션의 경우 [생체 인식 템플릿 보존](https://docs.didit.me/ko/console/data-retention.md#생체-인식-템플릿-보존)을 활성화할 수 있습니다. 이를 설정하면 Didit은 세션이 삭제된 후에도 사용자에 연결된 이미지가 없는 생체 인식 템플릿을 하나 보존하며, 해당 템플릿은 활성 세션 얼굴과 똑같이 얼굴 검색 및 자동 중복 감지에 참여합니다.보존된 템플릿에서 일치 항목이 발생하면 `source: "retained_template"`, 소유 사용자의 `vendor_user_id` 및 `vendor_data`, 그리고 `biometric_template_id`가 함께 보고됩니다. 해당 얼굴을 생성한 세션이 더 이상 존재하지 않기 때문에 세션 ID, 일치 이미지, 신원 세부 정보 또는 세션 상태는 포함되지 않습니다. 보존된 템플릿은 절대 차단 목록에 등록되지 않으며, 얼굴 차단 목록 항목은 별도의 독립적인 생체 인식 항목을 유지합니다.템플릿은 예정된 만료일, 사용자 삭제, 개인정보 삭제 요청, 또는 [Biometric Templates API](https://docs.didit.me/ko/management-api/biometric-templates/overview.md)나 Console의 **Lists → Biometric templates**를 통한 명시적 삭제(purge)가 있을 때까지 유지됩니다.## 유사도 백분율유사도 백분율은 잠재적 일치 항목을 판별하는 데 사용되는 핵심 지표입니다:- **높은 백분율(일반적으로 90% 이상)**: 두 얼굴이 동일 인물일 가능성이 매우 높음을 나타냅니다.
- **중간 백분율(70-89%)**: 추가 검토가 필요할 수 있는 잠재적 일치 항목임을 나타냅니다.
- **낮은 백분율(70% 미만)**: 서로 다른 개인일 가능성이 높음을 나타냅니다."일치"로 간주하는 정확한 임계값은 보안 요구사항에 따라 구성할 수 있습니다. 임계값을 높이면 오탐은 줄어들지만 미탐이 증가할 수 있습니다.## 활용 사례- **사기 방지**: 다중 계정 생성을 시도하는 사용자를 식별합니다.
- **향상된 KYC**: KYC 프로세스에 추가적인 검증 단계를 추가합니다.
- **규제 준수**: 중복 계정 감지에 대한 규제 요구사항을 충족합니다.
- **출입 통제**: 보안 수준이 높은 구역에서 사용자의 진위 여부를 확인합니다.
- **법 집행 기관**: 인가된 기관이 요주의 인물을 식별하도록 지원합니다.


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