> 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-pt-br/api-rest/identity-api/identity-api-reference/users/users-blacklists/search-user-blacklist.md).

# Buscar na lista negra de usuários

Realiza uma busca de Reconhecimento Facial 1:N dentro da lista negra compartilhada. Retorna os usuários que correspondem e que atendem ao limiar de similaridade configurado.

**Nota de privacidade**: Apenas o cliente que registrou originalmente um rosto receberá o userId na resposta. Outros clientes verão apenas a pontuação de similaridade.

### Endpoint

```
POST /users/blacklist/search
```

### Autenticação

| Tipo    | Localização | Nome          |
| ------- | ----------- | ------------- |
| API Key | Cabeçalho   | **x-api-key** |

### Corpo da solicitação

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

#### Parâmetros

| Parâmetro   | Tipo   | Obrigatório | Descrição                                                                                                                          |
| ----------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `face`      | string | **Sim**     | Imagem do rosto do usuário **codificada em Base64**. Os formatos suportados são **JPEG** e **PNG**. Tamanho máximo suportado: 5MB. |
| `threshold` | number | Não         | Valor que especifica a confiança mínima na correspondência facial para retornar um resultado. O valor padrão é **80%**.            |

#### Exemplo de solicitação

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

### Respostas

#### `200` Sucesso

#### Parâmetros de resposta

| Parâmetro              | Tipo   | Descrição                                                                                                                                                               |
| ---------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `matches`              | array  | Array de usuários correspondentes ordenados por pontuação de similaridade da maior para a menor.                                                                        |
| `matches[].userId`     | string | Identificador único do usuário correspondente. Este campo só é preenchido para o cliente que registrou originalmente o rosto. Outros clientes receberão um valor vazio. |
| `matches[].similarity` | number | Pontuação de similaridade entre 0 e 100, indicando a confiança da correspondência.                                                                                      |

#### Exemplo de resposta

```json
{
  "matches": [
    {
      "userId": "f7eab18f-e5d3-4dac-9d4d-cfb969ef848e",
      "similarity": 99.99953
    }
  ]
}
```

#### `400` Requisição inválida

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

#### `401` Não autorizado

```json
{
  "message": "Unauthorized"
}
```

#### `403` Proibido

```json
{
  "Message": "User is not authorized to access this resource with an explicit deny"
}
```

#### `404` Não encontrado

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