# Face Search

Within a collection, Face Search API allows you to search for previously registered persons using an image with a single that is obtained at a later time. The search is performed using a deep learning model trained on millions of face images. The search results are ranked by the similarity score, which is a number between 0 and 1, where 1 is a perfect match and 0 is a perfect mismatch. The max\_results parameter is optional and allows you to control the maximum number of returned results. By default, it is set to 1, but you can customize this number for your specific use case. 

If an image containing multiple faces is submitted for search, the results are returned in order of decreasing similarity score, provided each match meets the specified `min_score` threshold (default: 0.8).

## 1:N Face Search 

<mark style="color:green;">`POST`</mark> `/face-search`

This endpoint is for 1:N search of one face in an image within a collection

**Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |
| x-api-key    | `<your-api-key>`   |

**Body**

<table><thead><tr><th width="356">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>check_liveness</code></td><td><p>Required: yes</p><p>Type: boolean<br>Default value: false <br>Accepted values: false, true</p><p>Example:</p><pre class="language-json"><code class="lang-json">"check_liveness": false,
</code></pre><p>If set to true, the liveness check is performed during 1:N face search if the face is found. If no face is found, liveness is not checked.<br><br>Check <a href="liveness-detection"><mark style="color:red;"><strong>liveness image requirement here</strong></mark></a></p></td></tr><tr><td><code>collection_name</code></td><td><p>Required: Yes </p><p>Type: string<br>Example: </p><pre class="language-json"><code class="lang-json">"collection_name": "MyCollection",
</code></pre><p>Face search is performed within a specified collection. If the person is not enrolled in that collection, the result will be empty.</p></td></tr><tr><td><code>face_base_64</code></td><td><p>Required: Yes </p><p>Type: string<br>Example: </p><pre class="language-json"><code class="lang-json">"face_base_64": "U2Vjb25kIGltYWdl",
</code></pre><p>Use a Base64-encoded string to perform a 1:N face search. Each image should contain only one face. <br>For N:N face search, use POST /multi-face-search</p></td></tr><tr><td><code>min_similarity_score</code></td><td><p>Required: Yes </p><p>Type: float<br>Default value: 0.7 <br><br>Example: </p><pre class="language-json"><code class="lang-json">"min_similarity_score": 0.7
</code></pre><p>The default value is a good indicator to confirm the match. You can also use a score of 0.67 or higher if the images are of the same person but taken at different times (years apart).</p></td></tr><tr><td><code>max_results</code></td><td><p>Required: Yes</p><p>Type: integer<br>Example: </p><pre class="language-json"><code class="lang-json">"max_results": 1,
</code></pre><p>The max_results parameter allows you to control the maximum number of returned results. By default, it is set to 1, but you can customize this number for your specific use case.</p></td></tr></tbody></table>

## N:N Face Search

<mark style="color:green;">`POST`</mark> `/multi-face-search`

\<This endpoint is for N:N search multiple faces in an image within a collection>

**Body**

<table><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><code>collection_name</code></td><td><p>Required: Yes </p><p>Type: string<br>Example: </p><pre class="language-json"><code class="lang-json">"collection_name": "MyCollection",
</code></pre><p>Face search is performed within a specified collection. If the person is not enrolled in that collection, the result will be empty.</p></td></tr><tr><td><code>multi_face_img_base_64</code></td><td><p>Required: Yes </p><p>Type: string<br>Example: </p><pre class="language-json"><code class="lang-json">"multi_face_img_base_64": "U2Vjb25kIGltYWdl"
</code></pre><p>This enables searching for multiple faces within an image and retrieving results for all detected faces. If a face is not enrolled in the specified collection, its thumbnail will be returned without a similarity_score.</p></td></tr><tr><td><code>min_similarity_score</code></td><td><p>Required: Yes </p><p>Type: float<br>Default value: 0.7 <br>Example: </p><pre class="language-json"><code class="lang-json">"min_similarity_score": 0.7
</code></pre><p>The default value is a good indicator to confirm the match. You can also use a score of 0.67 or higher if the images are of the same person but taken at different times (years apart).</p></td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}
1:N Face Search<br>

```json
[
  {
    "face_base_64": "string",
    "metadata": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "person_id": "string",
    "person_name": "string",
    "similarity_score": 0.1
  }
]

```

\
N:N Face Search

```
{
  "person_search_results": [
    {
      "person_id": "string",
      "person_name": "string",
      "metadata": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
      },
      "face_base_64": "string",
      "similarity_score": 0.1
    }
  ],
  "unrecognized_face_thumbnails_base_64": [
    "string"
  ]
}

```

{% endtab %}

{% tab title="400" %}
A face could not be detected in the image(s)

```json
{
  "code": "ERR_FACE_NOT_DETECTED",
  "message": "A face could not be detected in the image(s)."
}
```

{% endtab %}

{% tab title="401" %}
Please use an API Key to access this endpoint

```json
{
  "code": "ERR_API_KEY_NOT_PRESENT",
  "message": "The API key is missing from the request."
}
```

{% endtab %}

{% tab title="403" %}
API Key is invalid. Please provide a valid API Key

```json
{
  "code": "ERR_API_KEY_NOT_VALID",
  "message": "The API key is not valid."
}
```

{% endtab %}

{% tab title="404" %}
The collection with the specified name does not exist

```json
{
  "code": "ERR_NOT_FOUND",
  "message": "The requested entity could not be found."
}
```

{% endtab %}

{% tab title="412" %}
Liveness error. The metadata contains the code that provides specifics about the error\
\
Common codes are:\
\
`EYES_CLOSED` || `FACE_CLOSE_TO_BORDER` || `FACE_CROPPED` || `FACE_NOT_LIVE` || `FACE_TOO_CLOSE` || `FACE_ANGLE_TOO_LARGE` || `FACE_IS_OCCLUDED` || `FACE_NOT_FOUND` || `FACE_TOO_SMALL` || `LICENSE_ERROR` || `TOO_MANY_FACES` || `UNKNOWN_ERROR`

```json
{
  "code": "ERR_LIVENESS_ERROR",
  "message": "A liveness error occurred. Please check the supplied image and the error metadata.",
  "metadata": {
    "code": "FACE_NOT_LIVE || .. || UNKNOWN_ERROR"
  }
}
```

{% endtab %}

{% tab title="422" %}
The images could not be decoded from base64

```json
{
  "code": "ERR_BASE64_IMAGE_CANNOT_BE_DECODED",
  "message": "The posted Base64 image(s) could not be decoded as JPEG/PNG bytes."
}  
```

{% endtab %}
{% endtabs %}