> 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/enroll-user-blacklist.md).

# Enroll User in Blacklist

Registers a new user's face in the shared blacklist. The userId must be unique within the collection. Only the client that registered the face can retrieve the full userId in search results and delete this entry.

### Endpoint

```
PUT /users/blacklist/{userId}
```

### Authentication

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

### Request body

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

#### Path parameters

| Parameter | Type   | Required | Description                                                                     |
| --------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `userId`  | string | **Yes**  | Unique user identifier. This ID must be unique within the blacklist collection. |

#### Parameters

| Parameter | Type   | Required | Description                                                                                                                  |
| --------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `face`    | string | **Yes**  | Image of the user's face **encoded in Base64**. The supported formats are **JPEG** and **PNG**. Maximum supported size: 5MB. |

#### Request example

```json
{
  "face": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}
```

{% hint style="warning" %}
**Maximum request size: 6 MB.** The Base64 image (`face`) and the remaining fields count toward this limit, with approximately 33% overhead compared with the original file (maximum original file size: approximately 4.5 MB). Compressed JPEG images of 1–2 MB or less are recommended. Although the service accepts images up to 5 MB, a 5 MB image takes up approximately 6.7 MB in Base64, so the gateway rejects it: the effective maximum original file size is approximately 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

User successfully registered in the blacklist. This response has no body.

#### `400` Bad Request

#### Example response: duplicate userId

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

#### Example response: invalid facial image

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

#### `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.
```
