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

# Entidades

> Busca de entidades canônicas por nome ou documento

Resolve um subject para o `entity_id` usado em [`POST /analyses`](/concepts/analyses).

## `GET /entities`

Busca por nome, documento (CPF/CNPJ), ou ambos.

**Escopo:** `entities:read`

### Parâmetros de busca

| Parâmetro     | Tipo                                                                                                                                                                            | Descrição                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `name`        | string                                                                                                                                                                          | Fragmento de nome. Deve conter ao menos 3 caracteres úteis.          |
| `document`    | string                                                                                                                                                                          | CPF ou CNPJ, completo ou parcial. Busca parcial exige `name` também. |
| `entity_type` | `person` \| `organization` \| `government_agency` \| `financial_institution` \| `political_party` \| `foreign_entity` \| `vessel` \| `aircraft` \| `notary_office` \| `unknown` | Filtro opcional de tipo de entidade.                                 |
| `limit`       | int (1-100, padrão 20)                                                                                                                                                          | Tamanho da página.                                                   |
| `offset`      | int (padrão 0)                                                                                                                                                                  | Deslocamento da página.                                              |

Ao menos um de `name`/`document` é obrigatório.

### Identificadores sempre mascarados

Toda resposta de busca traz os documentos (CPF/CNPJ) **mascarados**, nunca em texto puro:

* CPF: `***.123.456-**`
* CNPJ: `**.123.456/0001-**`

### Exemplo

```bash theme={null}
curl -G https://api.nlbs.ai/entities \
  -H "Authorization: Bearer nll_production_..." \
  --data-urlencode "name=Maria Silva" \
  --data-urlencode "limit=20"
```

```json theme={null}
{
  "items": [
    {
      "id": 410752090310337379,
      "entity_type": "person",
      "display_name": "Maria Silva",
      "legal_name": "Maria Silva",
      "identifiers": [
        { "identifier_type": "CPF", "value": "***.123.456-**", "is_masked": true }
      ],
      "aliases": ["M. Silva"]
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
```

### Erros específicos

Além dos [erros de autenticação](/authentication#erros-de-autenticação) e validação padrão:

| Status | Quando                                                                                                                                     |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `422`  | Nem `name` nem `document` foram informados, ou `name` tem menos de 3 caracteres úteis, ou uma busca parcial por documento veio sem `name`. |
| `409`  | A identidade do subject é ambígua (busca por documento completo).                                                                          |
| `503`  | A resolução de identidade está temporariamente indisponível.                                                                               |

Veja o catálogo completo de erros em [Erros](/concepts/errors).