> ## Documentation Index
> Fetch the complete documentation index at: https://docs.idmetagroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Biometric Blacklist — Face Enrollment

> Enroll face images into a biometric blacklist (watchlist). Enrollment is asynchronous.

Enroll face images into an existing biometric blacklist (watchlist). Enrollment is asynchronous: you submit a batch, get back an `upload_id`, then poll for the result.

**Base path:** `/v3/biometric-blacklists`

<Info>
  Scope is automatically limited to the authenticated user's company. You can only list, upload to, and poll uploads for blacklists owned by your company.
</Info>

## Authentication

Use the same authentication as all other v3 endpoints:

* **Bearer token** (Sanctum) in the `Authorization` header
* **HMAC signature headers**

See [Introduction to the API](/api-reference/introduction) for how to create an API token.

## Endpoints

| Step | Method | Path                                          | Purpose                                  |
| ---- | ------ | --------------------------------------------- | ---------------------------------------- |
| 1    | `GET`  | `/v3/biometric-blacklists`                    | List blacklists and get a `blacklist_id` |
| 2    | `POST` | `/v3/biometric-blacklists/{id}/faces`         | Upload up to 50 images per batch         |
| 3    | `GET`  | `/v3/biometric-blacklists/uploads/{uploadId}` | Poll until status is terminal            |

## Upload status values

Poll the upload status endpoint until `status` is `2`, `3`, or `4`.

| Value | Meaning                                          | Terminal? |
| ----- | ------------------------------------------------ | --------- |
| `0`   | Pending — queued, not yet started                | No        |
| `1`   | Processing — enrollment in progress              | No        |
| `2`   | Completed — all images enrolled                  | Yes       |
| `3`   | Failed — no images enrolled                      | Yes       |
| `4`   | Partially completed — some enrolled, some failed | Yes       |

## Recommended flow for large volumes

For high-volume enrollments (for example, 300k selfies):

<Steps>
  <Step title="Get the target blacklist">
    Call `GET /v3/biometric-blacklists` and note the `blacklist_id` you want to enroll into.
  </Step>

  <Step title="Chunk images into batches of 50">
    Split your image set into batches of up to 50 files per request.
  </Step>

  <Step title="Upload each batch">
    For each batch, call `POST /v3/biometric-blacklists/{id}/faces` and store the returned `upload_id`.
  </Step>

  <Step title="Poll each upload">
    Poll `GET /v3/biometric-blacklists/uploads/{uploadId}` every 3 minutes until `status` is `2`, `3`, or `4`.
  </Step>
</Steps>