> ## Documentation Index
> Fetch the complete documentation index at: https://developer.verilock.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Face Search (1:N)

> Detect duplicate identities across your organization using facial recognition.

Search a selfie against all previously verified faces in your organization's collection. Detects duplicate identities — where the same person verified under different names or credentials.

## Search for Duplicates

<ParamField body="session_id" type="string" required>
  The session whose selfie will be used as the search query.
</ParamField>

<ParamField body="threshold" type="number">
  Minimum similarity score to consider a match (50–100). Default: `90`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST \
    "https://verilock.io/api/v1/face-search" \
    -H "Authorization: Bearer qi_live_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "session_id": "ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "threshold": 90
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://verilock.io/api/v1/face-search",
      headers={
          "Authorization": "Bearer qi_live_your_api_key_here",
          "Content-Type": "application/json",
      },
      json={
          "session_id": "ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "threshold": 90,
      },
  )
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://verilock.io/api/v1/face-search', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer qi_live_your_api_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      session_id: 'ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890',
      threshold: 90,
    }),
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Duplicate Found theme={null}
  {
    "id": "fs_d4e5f6a1-b2c3-7890-fedc-ba0987654321",
    "duplicate_found": true,
    "highest_similarity": 97.82,
    "matches": [
      {
        "face_id": "aws-face-id-xxx",
        "similarity": 97.82,
        "session_id": "ses_previous-session-uuid",
        "external_image_id": "session-ses_previous-session-uuid"
      }
    ],
    "threshold_used": 90.00
  }
  ```

  ```json 200 No Duplicate theme={null}
  {
    "id": "fs_d4e5f6a1-...",
    "duplicate_found": false,
    "highest_similarity": null,
    "matches": [],
    "threshold_used": 90.00
  }
  ```
</ResponseExample>

## Get Search Result

```
GET /v1/face-search/{id}
```

Retrieve a previous face search result by ID.

## How It Works

<Steps>
  <Step title="Face indexing">
    When a session is approved, the selfie is automatically indexed into your organization's face collection.
  </Step>

  <Step title="Search query">
    When you call `POST /face-search`, the session's selfie is compared against all indexed faces in your collection.
  </Step>

  <Step title="Duplicate detection">
    If a match exceeds the threshold (self-matches excluded), it's flagged as a duplicate. A `face.duplicate_found` webhook is dispatched.
  </Step>
</Steps>

<Warning>
  Face collections are **per-organization**. Cross-organization searches are not supported.
</Warning>