> 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 the matching users that meet the configured similarity threshold.

**Privacy Notice**: 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**  | User's face image **encoded in Base64**. Supported formats are **JPEG** and **PNG**. Maximum supported size: 5MB. |
| `threshold` | number | No       | Value that specifies the minimum confidence in the facial match to return a result. The default value is **80%**. |

#### Request example

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

### 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 only filled in for the client that originally registered the face. Other clients will receive an empty value. |
| `matches[].similarity` | number | Similarity score between 0 and 100, indicating the confidence of the match.                                                                                         |

#### Response example

```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"
}
```