> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/users/users-blacklists/search-user-blacklist.md).

# Search User Blacklist

Performs a 1:N Facial Recognition search within the shared blacklist. Returns matching users whose similarity score meets the configured threshold.

**Privacy note**: Only the client that originally registered a face will receive the userId in the response. Other clients will only see the similarity score.

### Endpoint

```
POST /users/blacklist/search
```

### Authentication

| Type    | Location | Name          |
| ------- | -------- | ------------- |
| API Key | Header   | **x-api-key** |

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter   | Type   | Required | Description                                                                                                              |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `face`      | string | **Yes**  | Image of the user's face **encoded in Base64**. Supported formats are **JPEG** and **PNG**. Maximum supported size: 5MB. |
| `threshold` | number | No       | Value specifying the minimum confidence for a facial match to return a result. The default value is **80%**.             |

#### Request example

```json
{
  "face": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
  "threshold": 75.5
}
```

{% hint style="warning" %}
**Maximum request size: 6 MB.** The Base64 image (`face`) and the remaining fields count toward this limit, with \~33% overhead compared to the original file (maximum original file size \~4.5 MB). Compressed JPEG images of 1–2 MB or less are recommended. Although the service supports images up to 5 MB, a 5 MB image takes up \~6.7 MB in Base64 and the gateway rejects it: the effective maximum original file size is \~4.5 MB. If the limit is exceeded, the gateway responds `413` without processing the request. See [Request size limit](https://docs.facephi.com/pages/bc7bee9358079d52bafa44ad281828eb424e96fe#l%C3%ADmite-de-tama%C3%B1o-de-la-solicitud).
{% endhint %}

### Responses

#### `200` Success

#### Response parameters

| Parameter              | Type   | Description                                                                                                                                                         |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `matches`              | array  | Array of matching users, sorted by similarity score from highest to lowest.                                                                                         |
| `matches[].userId`     | string | Unique identifier of the matching user. This field is populated only for the client that originally registered the face. Other clients will receive an empty value. |
| `matches[].similarity` | number | Similarity score from 0 to 100, indicating the confidence of the match.                                                                                             |

#### Example response

```json
{
  "matches": [
    {
      "userId": "f7eab18f-e5d3-4dac-9d4d-cfb969ef848e",
      "similarity": 99.99953
    }
  ]
}
```

#### `400` Bad Request

```json
{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}
```

#### `401` Unauthorized

```json
{
  "message": "Unauthorized"
}
```

#### `403` Forbidden

```json
{
  "Message": "User is not authorized to access this resource with an explicit deny"
}
```

#### `404` Not Found

```json
{
  "status": 404,
  "title": "Not Found",
  "detail": "The server can't find the requested resource.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404"
}
```

#### `413` Payload Too Large

The request exceeds the maximum allowed size. The gateway rejects it **without processing it**: the response does not include `serviceResultCode` or `serviceTransactionId`. See [Request size limit](https://docs.facephi.com/pages/bc7bee9358079d52bafa44ad281828eb424e96fe#l%C3%ADmite-de-tama%C3%B1o-de-la-solicitud).

Request larger than 6 MB and up to 10 MB (`Content-Type: application/json`):

```json
{
  "message": "Request Too Long"
}
```

Request larger than 10 MB (10,485,760 bytes) (`Content-Type: text; charset=utf-8`, plain text, not JSON):

```
HTTP content length exceeded 10485760 bytes.
```
