> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/verify/biometric-verification/biometric-verification-v2/api-reference/blacklist-enrollment-and-search.md).

# Blacklist Enrollment & Search

Face Blacklist Check is a 1:N watchlist search that stops "known" bad actors who have been labelled before by clients. To enable this service, client needs to upload a gallery of faces (their blacklist) to VIDA via the Enrollment API. Then, with Search API, it can be incorporated in any step which requires blacklist check (e.g. Liveness, Authentication, etc).

A new standalone API is introduced to manage and search blacklisted faces from clients who requested to have this.

## Standalone API for Blacklist Management

### Endpoint

`POST` `/api/v2/face/blacklist`

### Supported Actions

<table><thead><tr><th width="205.80078125">Action</th><th>Description</th></tr></thead><tbody><tr><td>Search</td><td>Search for a given face image in the blacklist database.</td></tr><tr><td>Blacklist</td><td>Add a face image to the blacklist database.</td></tr></tbody></table>

## Enrollment&#x20;

<details>

<summary>Request</summary>

```json
{
  "transactionId": "random-uuid",
  "action": "blacklist",
  "payload": {
    "faceImage": "Base64 encoded image of face"
  }
}
```

</details>

<details>

<summary>Response</summary>

```json
{
  "transactionId": "c90008a4-987e-4247-9b00-2638417d37a4",
  "faceId": "2dd8a10e-0233-4439-88d5-e898331c34c9"
}
```

</details>

## Search

<details>

<summary>Request</summary>

```json
{
  "transactionId": "random-uuid",
  "action": "search",
    "searchOptions": {
      "threshold": 0.81,
      "maxResult":3
  },
  "payload": {
    "faceImage": "Base64 encoded image of face"
  }
}

```

</details>

<details>

<summary>Response</summary>

```json
{
  "transactionId": "4d462cf2-7a63-4593-876a-bd84a7d8e272",
  "matches": [
    {
      "faceId": "8976c7bd-206d-43f8-b361-2bf7ad2246e0",
      "matchScore": 1.0
    },
    {
      "faceId": "2506d9d7-f03b-4885-b779-dfaf470921a9",
      "matchScore": 1.0
    }
  ]
}
```

</details>