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

# API de dados

> Consulta de dados por CPF ou CNPJ e detalhe de processo por número

A API de dados tem duas rotas. Em `POST /dados/consultar` você envia um CPF ou CNPJ e a lista de datasets que quer, e recebe um bloco resumido para cada dataset pedido. Em `GET /dados/processos/{numero}` você recebe o detalhe de um processo pelo número CNJ, com os movimentos paginados (veja [Detalhe de processo](https://docs.nlbs.ai/dados/datasets.md#detalhe-de-um-processo)). Cada dataset tem uma página própria com a rota já preenchida: veja o [catálogo de datasets](https://docs.nlbs.ai/dados/datasets.md).

```bash theme={null}
curl -X POST https://api.nlbs.ai/dados/consultar \
  -H "X-API-Key: $NLLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"documento": "529.982.247-25", "datasets": ["pep", "processos"]}'
```

A chave de API vai no cabeçalho `X-API-Key: <chave>`: veja [Autenticação](https://docs.nlbs.ai/authentication.md). A rota valida a chave e o escopo por dataset: `POST /dados/consultar` exige `dados:consultar` e `dados:<dataset>` para cada dataset pedido (`dados:pep`, `dados:processos`, ...). Faltando um, responde `403` (`escopo_insuficiente`). `GET /dados/processos/{numero}` exige `dados:processos`. Todos os exemplos desta aba usam documentos e números sintéticos.

## Requisição

| Campo | Tipo | Descrição |
| - | - | - |
| `documento` | string | CPF ou CNPJ, com ou sem pontuação. Deve ter dígitos verificadores válidos. |
| `datasets` | lista | Um ou mais de `pep`, `processos`, `faccionados`, `midia`, `sancoes`, `vinculos`, `ubo`, `identidade`, `beneficios`. Sem repetidos. `ubo` exige CNPJ e `identidade` exige CPF. |
| `processos` | objeto, opcional | `cursor` (opaco, da página anterior) e `limite` (1 a 100, padrão 25). Sem `offset`. |

O cabeçalho opcional `Idempotency-Key` faz a mesma chave, em 24 horas a partir da primeira chamada, devolver a mesma resposta, sem repetir a leitura.

## Resposta

```json theme={null}
{
  "documento": "52998224725",
  "tipo": "cpf",
  "encontrado": false,
  "consultado_em": "2026-01-15T12:00:00Z",
  "datasets": {
    "pep": { "encontrado": false, "itens": [] },
    "processos": { "encontrado": false, "itens": [], "total": 0, "proximo_cursor": null }
  }
}
```

Só aparecem os datasets pedidos. Cada bloco traz `encontrado` e `itens` resumidos. O bloco de `processos` traz ainda `total` e `proximo_cursor`: repita a chamada com `processos.cursor` até `proximo_cursor` vir `null`.

## Mascaramento de documentos de terceiros

Quando um item cita uma pessoa ou empresa que não é a consultada (por exemplo, uma parte de um processo), o documento dela vem mascarado e o nome vem inteiro. O documento da entidade consultada não é mascarado.

| Tipo | Documento sintético | Como vem na resposta | Visível |
| - | - | - | - |
| CPF | `529.982.247-25` | `***.982.***-**` | posições 4 a 6 |
| CNPJ | `11.222.333/0001-81` | `**.***.333/***-**` | posições 6 a 8 |

Continue em [Datasets](https://docs.nlbs.ai/dados/datasets.md) e [Erros](https://docs.nlbs.ai/dados/erros.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.