> ## Documentation Index
> Fetch the complete documentation index at: https://documentacao.legitimuz.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Listar verificações por titular
> GET /public/validations-persons: a verificação mais recente de cada titular, com filtros, paginação e o resultado de cada etapa.
Lista os titulares da conta, cada um com a verificação mais recente e o resultado de cada etapa.
```bash title="Listar as verificações aprovadas ou em análise" theme={null}
curl -G https://api-core.legitimuz.com/public/validations-persons \
-H "X-API-Key: $LEGITIMUZ_API_KEY" \
--data-urlencode "status=approved,review" \
--data-urlencode "from=2026-09-01T00:00:00Z" \
--data-urlencode "per_page=50"
```
## Requisitos
| Requisito | Detalhe |
| - | - |
| Autenticação | Header `X-API-Key` com a chave da integração (`lz_...`). Veja [autenticação](/start/authentication) |
| Permissão | **Ver verificações**. Baixar imagens exige também **Ver mídia da verificação**. Nascem desmarcadas: veja [como conceder](/platform/tokens#permissões-de-leitura) |
| IP liberado | Só IPs liberados pela Legitimuz. De outro IP, a chamada é barrada antes de chegar à API, com `403`, mesmo com chave e permissão corretas. Para liberar, fale com o [suporte](https://painel.legitimuz.com/support) e informe o IP fixo ou a faixa CIDR |
| Alcance | Só as verificações da integração da chave, no ambiente dela. As de outra integração da conta não aparecem |
## Parâmetros
Todos são opcionais e vão na query string. Parâmetro desconhecido ou inválido responde
`400 E_VALIDATION_FAILURE`.
### Filtros
| Parâmetro | Formato | Filtra por |
| - | - | - |
| `status` | Um ou mais, separados por vírgula | [Status](/api/verification-status) da verificação |
| `flow` | `public_id`, um ou mais separados por vírgula | Fluxo |
| `journey` | `onboarding` ou `transactional` | Jornada completa ou reduzida |
| `document_type` | Hoje, `cpf` | Tipo do documento do titular |
| `captured_document_type` | Uma ou mais famílias, separadas por vírgula | Família do documento que o titular mostrou |
| `capture_method` | `standard_camera`, `gallery` ou `digital_document`, separados por vírgula | Por onde a captura entrou |
| `from` | ISO 8601 com fuso | Criadas a partir do instante, inclusive |
| `to` | ISO 8601 com fuso | Criadas até o instante, exclusive |
As famílias de `captured_document_type` são `cnh`, `cnh_digital`, `ctps`, `cpf`, `passport`, `rg`,
`rg_digital`, `rne`, `rnm`, `dni`, `dni_digital`, `cin`, `cin_digital` e `invalid`.
A lista cobre só as verificações da integração da chave, então não há filtro de integração:
`integration` responde `400`. Para ler uma verificação pelo `public_id`, use
[consultar verificação](/api/get-verification).
### Paginação
| Parâmetro | Padrão | Limites |
| - | - | - |
| `page` | `1` | A partir de 1 |
| `per_page` | `25` | De 1 a 100 |
## Resposta
`200` com `data` (um item por titular) e `pagination`, do titular com a verificação mais recente ao
mais antigo. Header `Cache-Control: no-store`.
### Envelope
| Campo | Tipo | Descrição |
| - | - | - |
| `data` | `object[]` | Um item por titular, com a verificação mais recente no recorte |
| `pagination.page` | `integer` | A página devolvida |
| `pagination.per_page` | `integer` | Itens por página |
| `pagination.total` | `integer` | Titulares do recorte, somando todas as páginas |
### Verificação
Campos de cada item de `data`.
| Campo | Tipo | Descrição |
| - | - | - |
| `public_id` | `string` | Identificador. Use em [consultar verificação](/api/get-verification) e [baixar imagens](/api/verification-files) |
| `ref_id` | `string \| null` | `ref_id` enviado na criação |
| `status` | `string` | Um dos cinco [status](/api/verification-status) |
| `journey` | `string` | `onboarding` ou `transactional` |
| `flow` | `object \| null` | Fluxo: `public_id` e `name` |
| `integration` | `object \| null` | Integração dona: `public_id` e `name` |
| `identity_score` | `number \| null` | Score de identidade, de 0 a 100 (maior é melhor). Veja [score](/platform/score) |
| `risk_score` | `number \| null` | Score de risco, de 0 a 100 (maior é pior). Mesmo campo do webhook [`verification.scored`](/webhooks/events#verificationscored) |
| `created_at` | `string` | Criação. ISO 8601 em UTC |
| `updated_at` | `string` | Última atualização. ISO 8601 em UTC |
| `decided_at` | `string \| null` | Quando o fluxo terminou e a verificação recebeu `approved`, `reproved` ou `review`. ISO 8601 em UTC. `null` enquanto está em andamento. Uma decisão de analista depois disso fica em `manual_decision.at` |
| `verifications_count` | `integer` | Verificações do titular na integração da chave, dentro do recorte dos filtros |
| `last_verification_at` | `string` | Verificação mais recente do titular. ISO 8601 em UTC |
| `manual_decision` | `object \| null` | Decisão de um analista no dashboard: `at` (ISO 8601 em UTC), `reason` e `note` (texto livre). `null` sem decisão |
| `attempts.document` | `integer` | Tentativas de captura do documento |
| `attempts.liveness` | `integer` | Tentativas da prova de vida |
| `notices` | `object[]` | [Avisos](#avisos) da jornada fora de qualquer etapa |
`manual_decision.reason` é `unreadable_document`, `incompatible_document_data`,
`incompatible_selfie`, `screenshot_photo`, `expired_document`, `unaccepted_document`, `fraud`,
`manual_approve` ou `other`.
### Titular
Campos de cada item de `data`. **Mascarado** indica o que vem mascarado sem a permissão **Ver dados
cadastrais desmascarados**.
| Campo | Tipo | Mascarado | Descrição |
| - | - | - | - |
| `person_name` | `string \| null` | Sim | Nome do titular |
| `document` | `string` | Sim | Documento do titular |
| `document_type` | `string` | Não | Tipo do documento. Hoje, `cpf` |
| `person.name` | `string \| null` | Sim | Nome |
| `person.birthdate` | `string \| null` | Sim | Data de nascimento, em `AAAA-MM-DD` |
| `person.mother_name` | `string \| null` | Sim | Nome da mãe |
| `person.gender` | `string \| null` | Não | Gênero registrado |
| `person.situation` | `string \| null` | Não | Situação cadastral do CPF |
| `person.pep` | `boolean \| null` | Não | Se o titular é pessoa exposta politicamente |
| `person.pep_origin` | `string \| null` | Não | Por que é PEP: `holder` (o próprio titular) ou `relative` (um parente). `null` quando `pep` não é `true` |
| `person.deceased` | `boolean \| null` | Não | Se há registro de óbito. `null` quando a consulta não foi feita |
### Listas restritivas
`restrictive_lists` traz as listas restritivas de CPF **da sua conta** em que o documento do titular
aparece, cada uma com `public_id` e `name`. Vem `[]` quando o documento não está em nenhuma. Listas
de outras contas nunca aparecem. São as mesmas listas que o dashboard mostra na verificação.
| Campo | Tipo | Descrição |
| - | - | - |
| `restrictive_lists[].public_id` | `string` | Identificador da lista |
| `restrictive_lists[].name` | `string` | Nome da lista, como cadastrado no dashboard |
### Máscara
A máscara mantém a primeira letra de cada palavra do nome e só o ano do nascimento:
| Campo | Sem a permissão | Com a permissão |
| - | - | - |
| `document` | `***.000.000-**` | `000.000.000-00` |
| `person_name` e `person.name` | `M**** O*******` | `Maria Oliveira` |
| `person.mother_name` | `A** O*******` | `Ana Oliveira` |
| `person.birthdate` | `1990-**-**` | `1990-04-12` |
### Etapas
`steps` tem `ocr`, `liveness`, `facematch`, `documentoscopy` e `biometric`. Todas têm `state`
(`approved`, `failed` ou `pending`) e `notices` ([avisos](#avisos) da etapa), mais estes campos:
| Etapa | Campo | Tipo | Descrição |
| - | - | - | - |
| `ocr` | `name_match`, `document_match`, `birthdate_match` | `boolean \| null` | Se o valor lido no documento confere com o cadastro |
| `ocr` | `document_type` | `string \| null` | A família do documento lido |
| `liveness` | `score` | `number \| null` | Score da prova de vida |
| `facematch` | `similarity` | `number \| null` | Similaridade entre a selfie e o documento |
| `documentoscopy` | `result` | `string \| null` | `approved`, `manual` ou `disapproved` |
| `documentoscopy` | `score` | `number \| null` | Score da análise de autenticidade do documento |
| `biometric` | `score` | `number \| null` | Score da busca biométrica |
* `skipped` aparece só em `ocr` e `documentoscopy`, na jornada `transactional`, que não as executa.
* Em `documentoscopy`, `state` é `failed` para `manual` e para `disapproved`. Para separar, use
`result`: `manual` segue para análise de um analista.
### Avisos
Cada aviso tem `code`, `severity` (`info` ou `alerta`) e `label`. Compare pelo `code`: o `label` é
texto em português do dashboard e pode mudar.
```json title="Resposta 200" theme={null}
{
"data": [
{
"public_id": "019f0000-0000-7000-8000-000000000001",
"ref_id": "pedido-4471",
"person_name": "M**** O*******",
"document": "***.000.000-**",
"document_type": "cpf",
"flow": { "public_id": "019f0000-0000-7000-8000-0000000000f1", "name": "Onboarding" },
"integration": { "public_id": "019f0000-0000-7000-8000-0000000000a1", "name": "Loja online" },
"status": "approved",
"journey": "onboarding",
"identity_score": 94,
"risk_score": 12,
"created_at": "2026-09-14T17:30:12.000Z",
"updated_at": "2026-09-14T17:31:03.000Z",
"decided_at": "2026-09-14T17:30:58.000Z",
"manual_decision": null,
"verifications_count": 2,
"last_verification_at": "2026-09-14T17:30:12.000Z",
"person": {
"name": "M**** O*******",
"birthdate": "1990-**-**",
"mother_name": "A** O*******",
"gender": null,
"situation": null,
"pep": false,
"pep_origin": null,
"deceased": false
},
"restrictive_lists": [],
"steps": {
"ocr": {
"state": "approved",
"name_match": true,
"document_match": true,
"birthdate_match": true,
"document_type": "cnh",
"notices": [
{ "code": "name_found", "severity": "info", "label": "Nome encontrado no documento" }
]
},
"liveness": { "state": "approved", "score": 98, "notices": [] },
"facematch": { "state": "approved", "similarity": 91, "notices": [] },
"documentoscopy": { "state": "approved", "result": "approved", "score": 96, "notices": [] },
"biometric": { "state": "pending", "score": null, "notices": [] }
},
"attempts": { "document": 1, "liveness": 1 },
"notices": []
}
],
"pagination": { "page": 1, "per_page": 50, "total": 1 }
}
```
## Códigos de resposta
| HTTP | Código | Quando |
| - | - | - |
| `200` | — | Página devolvida. Sem resultado, `data` vem vazio |
| `400` | `E_VALIDATION_FAILURE` | Parâmetro desconhecido ou inválido, como `per_page` acima de 100. Busca por CPF ou por `id` não existe nesta rota |
| `401` | `E_UNAUTHORIZED_ACCESS` | Chave ausente, inválida, expirada ou revogada |
| `403` | `E_FORBIDDEN` | Chave sem a permissão **Ver verificações**. IP não liberado também recebe `403`, mas antes de chegar à API: veja [requisitos](#requisitos) |
| `429` | `E_RATE_LIMITED` | Teto de chamadas por minuto na mesma chave, hoje de 500. Respeite `Retry-After`. Veja [limites](/api/errors#limites-de-uso) |
| `500` | `E_INTERNAL_SERVER_ERROR` | Falha inesperada |
Corpo de erro: [erros da API](/api/errors).
## Próximo passo
Uma verificação pelo `public_id`, com os mesmos campos.
A selfie e o documento de uma verificação, por URL assinada.
Os cinco valores e o que cada um significa.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.