> ## 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 रिपोर्ट: मिलान परिणाम JSON

> Didit के चेहरा खोज 1:N रिपोर्ट का संदर्भ: धोखाधड़ी जांच के लिए मिलान सत्र ID, समानता प्रतिशत, ब्लॉकलिस्ट फ़्लैग और उपयोगकर्ता विवरण।

## अवलोकन

चेहरा खोज एक **1:N** बायोमेट्रिक खोज है: Didit आपके `user_image` में सबसे बड़े पाए गए चेहरे को लेता है और उसे आपके एप्लिकेशन के चेहरा खोज इंडेक्स के विरुद्ध खोजता है — सत्यापन सत्रों से नामांकित चेहरे, सहेजे गए स्टैंडअलोन API कॉल, सीधे उपयोगकर्ता-प्रोफ़ाइल चेहरा अपलोड, और आपकी ब्लॉक/अनुमति सूचियाँ। यह चेहरा मिलान से अलग है, जो कि **1:1** है — चेहरा मिलान किसी विशिष्ट दस्तावेज़ पर मौजूद पोर्ट्रेट के साथ सेल्फ़ी की तुलना करता है, जबकि चेहरा खोज यह सवाल पूछता है कि "क्या हमने इस व्यक्ति को पहले कभी कहीं देखा है?"।

रिपोर्ट पार्स करने से पहले दो व्यवहारों को समझना उपयोगी है:

* **केवल ब्लॉकलिस्ट मिलान ही अस्वीकृत करते हैं।** `face_search.status` केवल तभी `Declined` होता है जब `FACE_IN_BLOCKLIST` या `POSSIBLE_FACE_IN_BLOCKLIST` चेतावनी ट्रिगर होती है। केवल डुप्लिकेट मिलान `Approved` लौटाते हैं — सिर्फ़ `status` ही नहीं, बल्कि `matches` और `warnings` की भी जाँच करें।
* **वैकल्पिक संग्रहण और नामांकन।** जब `save_api_request=true` (डिफ़ॉल्ट) होता है, तो कॉल को API-प्रकार के सत्र के रूप में सहेजा जाता है और खोजे गए चेहरे को आपके चेहरा खोज इंडेक्स में नामांकित किया जाता है। चेहरा खोज कॉल द्वारा नामांकित चेहरों को **भविष्य के चेहरा खोज परिणामों से बाहर रखा जाता है**, ताकि बार-बार की जाने वाली खोजें कभी एक-दूसरे से मेल न खाएं। वन-शॉट क्वेरी के लिए `save_api_request=false` पास करें: कुछ भी संग्रहीत नहीं किया जाता है और चेहरा नामांकित नहीं होता है।

## परिणाम कहाँ दिखाई देते हैं

चेहरा खोज एक स्टैंडअलोन API है। खोज परिणाम शीर्ष स्तर पर एक एकल `face_search` ऑब्जेक्ट के रूप में, **केवल `POST /v3/face-search/` रिस्पॉन्स में सिंक्रोनस रूप से** लौटाए जाते हैं:

```text theme={null}
POST /v3/face-search/  ──▶  { "request_id": …, "face_search": { … }, "vendor_data": …, "metadata": …, "created_at": … }
```

कहीं भी कोई बहुवचन `face_searches[]` ऐरे नहीं है — सत्र निर्णय endpoint पर `id_verifications[]`, `aml_screenings[]`, और `liveness_checks[]` द्वारा उपयोग किया जाने वाला बहुवचन-ऐरे कन्वेंशन यहाँ लागू नहीं होता है।

जब `save_api_request=true` (डिफ़ॉल्ट) होता है, तो कॉल को API-प्रकार के सत्र के रूप में भी सहेजा जाता है:

* **Business Console** — सत्र आपकी सत्र सूची में खोज छवि, मिलान और चेतावनियों के साथ दिखाई देता है।
* **`GET /v3/session/{sessionId}/decision/`** — इसे लौटाए गए `request_id` को सत्र ID के रूप में उपयोग करके पुनः प्राप्त किया जा सकता है। सहेजा गया डेटा `features[]` में एक `FACE_SEARCH` प्रविष्टि के रूप में और संग्रहीत `matches` (ताज़ा हस्ताक्षरित `match_image_url` मानों के साथ) और `warnings` ले जाने वाले `liveness_checks[]` आइटम के रूप में दिखाई देता है — एक `face_search` ऑब्जेक्ट के रूप में **नहीं**।

जब `save_api_request=false` होता है, तो `request_id` एक अस्थायी सहसंबंध UUID होता है: सत्र कभी संग्रहीत नहीं होता है, इसलिए इसे कंसोल या निर्णय endpoint से प्राप्त नहीं किया जा सकता है।

## स्कीमा

प्रामाणिक फ़ील्ड तालिकाओं के लिए [डेटा मॉडल संदर्भ में चेहरा खोज](https://docs.didit.me/hi/reference/data-models.md#चेहरा-खोज) देखें। नीचे दिया गया स्वरूप दर्शाता है कि रनटाइम पर endpoint वास्तव में क्या लौटाता है।

```typescript theme={null}
interface FaceSearchResponse {
  request_id: string;            // UUID — the persisted session id when save_api_request=true
  face_search: {
    status: 'Approved' | 'Declined';
    total_matches: number;       // 0-5, length of matches[]
    matches: FaceSearchMatch[];  // capped at 5, ordered by similarity
    user_image: {                // always present
      entities: {
        bbox: [number, number, number, number];
        confidence: number;      // 0-1, one entry per detected face
      }[];
      best_angle: 0 | 90 | 180 | 270;
    };
    warnings: Warning[];
  };
  vendor_data: string | null;    // echoed from the request
  metadata: object | null;       // echoed from the request
  created_at: string;            // ISO 8601, e.g. "2026-06-12T01:04:42.763237+00:00"
}

interface FaceSearchMatch {
  session_id: string | null;     // UUID of the matched session; null for non-session matches
  session_number: number | null; // Console-friendly number; null for non-session matches
  similarity_percentage: number; // 0-100
  source: 'session' | 'imported' | 'list_entry' | 'retained_template';
  vendor_data: string | null;    // the matched session's, imported profile's, or retained template's User vendor_data
  vendor_user_id: string | null; // UUID of the linked User; null for list_entry matches and sessions without a User
  biometric_template_id: string | null; // set only for retained_template matches
  verification_date: string | null;  // "YYYY-MM-DDThh:mm:ssZ"; null for list_entry matches; the retention date for retained_template matches
  user_details: {
    full_name: string | null;
    document_type: string | null;
    document_number: string | null;
  } | null;                      // null when the matched session has no document data
  match_image_url: string | null; // signed URL when save_api_request=true; raw storage path otherwise; null for retained_template matches
  status: 'Approved' | 'Declined' | 'In Review' | null;  // the matched session's status
  is_blocklisted: boolean;
  is_allowlisted: boolean;
  api_service: 'ID_VERIFICATION' | 'FACE_MATCH' | 'AGE_ESTIMATION' | 'POA' | 'AML'
             | 'PASSIVE_LIVENESS' | 'DATABASE_VALIDATION' | 'PHONE_VERIFICATION'
             | 'EMAIL_VERIFICATION' | null;  // null when the match comes from a workflow session
}

interface Warning {
  risk: string;
  feature: 'LIVENESS';           // always LIVENESS on this endpoint
  additional_data: object | null;
  log_type: 'error' | 'warning' | 'information';
  short_description: string;
  long_description: string;
}
```

फ़ील्ड नोट्स:

* **`matches[]` समानता की न्यूनतम सीमा से ऊपर 5 प्रविष्टियों तक सीमित है**, जो घटती हुई समानता के क्रम में व्यवस्थित होती हैं (`search_type=blocklisted_or_approved` ब्लॉकलिस्ट की गई प्रविष्टियों को पहले, फिर अनुमति सूची वाली, फिर समानता को रैंक करता है)।
* **`source`** आपको बताता है कि मिलान किया गया चेहरा कहाँ से नामांकित किया गया था: `session` — एक सत्यापन सत्र या एक सहेजी गई स्टैंडअलोन API कॉल; `imported` — सीधे उपयोगकर्ता प्रोफ़ाइल पर अपलोड किया गया चेहरा; `list_entry` — आपकी किसी सूची से जुड़ा चेहरा; `retained_template` — एक छवि-मुक्त [बायोमेट्रिक टेम्पलेट](https://docs.didit.me/hi/management-api/biometric-templates/overview.md) जिसे एप्लिकेशन ने स्रोत सत्र को हटाने के बाद बनाए रखा था। `imported`, `list_entry`, और `retained_template` मिलानों के लिए `session_id`, `session_number`, `status`, और `api_service` का मान `null` होता है।
* **`retained_template` मिलान** `vendor_user_id`, `vendor_data`, और `biometric_template_id` ले जाते हैं, और `match_image_url`, `user_details`, तथा सत्र से संबंधित हर चीज़ के लिए हमेशा `null` होते हैं: जिस सत्र ने चेहरा बनाया था वह अब मौजूद नहीं है और टेम्पलेट में कोई छवि या पहचान डेटा नहीं होता है। बनाए रखे गए टेम्पलेट के लिए `is_blocklisted` हमेशा `false` होता है; एक ब्लॉकलिस्ट किए गए चेहरे की रिपोर्ट `list_entry` मिलान के रूप में अलग से दी जाती है। `DELETE /v3/biometric-templates/{biometric_template_id}/` के साथ टेम्पलेट को पर्ज करें।
* **`api_service`** मिलान किए गए सत्र का स्टैंडअलोन API प्रकार है (अपरकेस, उदा. `PASSIVE_LIVENESS`) और जब मिलान किया गया चेहरा किसी सामान्य वर्कफ़्लो सत्यापन सत्र से आया हो तो यह `null` होता है।
* **`user_details`** मिलान किए गए सत्र के दस्तावेज़ सत्यापन से आता है। `source: imported` मिलानों के लिए इसे इसके बजाय उपयोगकर्ता प्रोफ़ाइल से पॉप्युलेट किया जाता है (`full_name` सेट, `document_type`/`document_number` null); जब कोई पहचान डेटा मौजूद नहीं होता है (उदाहरण के लिए केवल-लाइवनेस सत्र) तो यह `null` होता है।
* **चेतावनियों का स्वरूप वर्कफ़्लो चेतावनियों की तुलना में संक्षिप्त होता है**: कोई `node_id` नहीं होता है। प्रलेखित रिस्पॉन्स अनुबंध (`FaceSearchResponseSerializer`) पाँच फ़ील्ड `risk`, `additional_data`, `log_type`, `short_description`, `long_description` घोषित करता है; रनटाइम payload अतिरिक्त रूप से `feature` ले जाता है, जो यहाँ हमेशा `"LIVENESS"` होता है। [चेहरा खोज चेतावनियाँ](https://docs.didit.me/hi/core-technology/face-search/warnings-face-search.md) देखें।
* **एक ही उपयोगकर्ता के मिलानों को बाहर नहीं रखा जाता है** — वर्कफ़्लो डुप्लिकेट डिटेक्शन के विपरीत, स्टैंडअलोन endpoint समान `vendor_data` वाले पिछले सत्रों को फ़िल्टर नहीं करता है, इसलिए लौटने वाला वैध उपयोगकर्ता अपने स्वयं के पुराने सत्रों से मेल खाता है।

## स्थिति मान

शीर्ष-स्तरीय `face_search.status` को `warnings[]` से प्राप्त किया जाता है। मिलान-स्तरीय `status` **मिलान किए गए सत्र** के सत्यापन परिणाम को दर्शाता है और स्वतंत्र होता है।

| मान | यह कब दिखाई देता है |
| - | - |
| `Approved` | कोई ब्लॉकलिस्ट चेतावनी ट्रिगर नहीं हुई। इसमें वह मामला भी शामिल है जहाँ डुप्लिकेट मिलान पाए गए थे — डुप्लिकेट केवल सूचनात्मक संकेत हैं, अस्वीकृति नहीं। |
| `Declined` | एक `FACE_IN_BLOCKLIST` या `POSSIBLE_FACE_IN_BLOCKLIST` चेतावनी ट्रिगर हुई — खोज छवि आपकी चेहरे की ब्लॉकलिस्ट में मौजूद किसी चेहरे से मेल खाती है। |

नोट: जब खोज छवि में कोई पता लगाने योग्य चेहरा नहीं होता है, तो API `face_search` ऑब्जेक्ट बनने से **पहले** `{"error": "No face detected in the image"}` के साथ HTTP `400` लौटाता है — उस मामले के लिए कोई `Declined` स्थिति नहीं होती है। अपर्याप्त क्रेडिट किसी भी छवि प्रसंस्करण से पहले HTTP `403` लौटाते हैं।

## उदाहरण

### Approved — डुप्लिकेट मिलान, कोई ब्लॉकलिस्ट नहीं

```json theme={null}
{
  "request_id": "5e0c3a1f-7b2d-4c8e-9f10-2a3b4c5d6e7f",
  "face_search": {
    "status": "Approved",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
        "session_number": 1024,
        "similarity_percentage": 87.42,
        "source": "session",
        "vendor_data": "user-9",
        "verification_date": "2025-11-20T09:15:00Z",
        "user_details": {
          "full_name": "Jane Marie Doe",
          "document_type": "Passport",
          "document_number": "X1234567"
        },
        "match_image_url": "https://<media-host>/face/9c8b7a6d/reference.jpg?signature=...",
        "status": "Approved",
        "is_blocklisted": false,
        "is_allowlisted": false,
        "api_service": null
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [40, 40, 120, 120],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "DUPLICATED_FACE",
        "feature": "LIVENESS",
        "additional_data": {
          "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
          "duplicated_session_number": 1024,
          "api_service": null
        },
        "log_type": "information",
        "short_description": "Duplicated face from other approved session",
        "long_description": "The system identified a duplicated face from another approved session, requiring further investigation."
      }
    ]
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}
```

### Declined — ब्लॉकलिस्ट मिलान

```json theme={null}
{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "face_search": {
    "status": "Declined",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "session_number": 323442,
        "similarity_percentage": 99.99,
        "source": "session",
        "vendor_data": "user-1",
        "verification_date": "2025-01-01T00:00:00Z",
        "user_details": {
          "full_name": "Jane Marie Doe",
          "document_type": "ID",
          "document_number": "X1234567"
        },
        "match_image_url": "https://<media-host>/face/3f6a1c2e/reference.jpg?signature=...",
        "status": "Approved",
        "is_blocklisted": true,
        "is_allowlisted": false,
        "api_service": "PASSIVE_LIVENESS"
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [40, 40, 120, 120],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "FACE_IN_BLOCKLIST",
        "feature": "LIVENESS",
        "additional_data": {
          "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
          "blocklisted_session_number": 323442,
          "api_service": "PASSIVE_LIVENESS"
        },
        "log_type": "error",
        "short_description": "Face in blocklist",
        "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
      }
    ]
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}
```

## संबंधित

* [चेहरा खोज चेतावनियाँ](https://docs.didit.me/hi/core-technology/face-search/warnings-face-search.md) — प्रत्येक चेतावनी कोड जो खोज जारी कर सकती है
* [चेहरा खोज API संदर्भ](https://docs.didit.me/hi/standalone-apis/face-search.md) — अनुरोध पैरामीटर और `search_type` मोड
* [डेटा मॉडल — चेहरा खोज](https://docs.didit.me/hi/reference/data-models.md#चेहरा-खोज) — कैनोनिकल स्कीमा
* [webhook](https://docs.didit.me/hi/integration/webhooks.md) — सहेजे गए सत्रों के लिए `status.updated` payloads

> [!NOTE]
>
> जब `save_api_request=true` होता है, तो `match_image_url` मान हस्ताक्षरित, अल्पकालिक URL होते हैं — ताज़ा URL प्राप्त करने के लिए लौटाए गए `request_id` के साथ सत्र निर्णय endpoint को पुनः फ़ेच करें। जब `save_api_request=false` होता है, तो वे आंतरिक स्टोरेज पाथ होते हैं और सीधे डाउनलोड करने योग्य नहीं होते हैं। अपनी ओर केवल मिलान किए गए सत्र id, स्थिति और `similarity_percentage` को संग्रहीत करें — अंतर्निहित बायोमेट्रिक छवि को बनाए न रखें।


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