> 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/api-reference/blacklist-enrollment-and-search.md).

# Blacklist Enrollment and 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 require blacklist check (e.g. Liveness, Authentication, etc). 

### Standalone API for Blacklist Management <a href="#standalone-api-for-blacklist-management" id="standalone-api-for-blacklist-management"></a>

A new standalone API is introduced to manage and search blacklisted faces from client who requested to have&#x20;

#### Endpoint <a href="#endpoint" id="endpoint"></a>

`POST` `/api/v1/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;

**Request**

<details>

<summary>JSON Response</summary>

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

```

</details>

**Response**

<details>

<summary>JSON Response</summary>

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

</details>

## Search

**Request**

<details>

<summary>JSON Response</summary>

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

```

</details>

**Response**

<details>

<summary>JSON 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>