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.

GET /public/validations-persons

Listar as verificações aprovadas ou em análise

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"

Resposta 200

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

Lista os titulares da conta, cada um com a verificação mais recente e o resultado de cada etapa.

Listar as verificações aprovadas ou em análise

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
Permissão	Ver verificações. Baixar imagens exige também Ver mídia da verificação. Nascem desmarcadas: veja como conceder
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 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 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.

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 e baixar imagens
ref_id	string | null	ref_id enviado na criação
status	string	Um dos cinco 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
risk_score	number | null	Score de risco, de 0 a 100 (maior é pior). Mesmo campo do webhook verification.scored
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 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 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.

Resposta 200

{
  "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
429	E_RATE_LIMITED	Teto de chamadas por minuto na mesma chave, hoje de 500. Respeite Retry-After. Veja limites
500	E_INTERNAL_SERVER_ERROR	Falha inesperada

Corpo de erro: erros da API.

Próximo passo

Consultar verificação

Uma verificação pelo public_id, com os mesmos campos.

Baixar imagens

A selfie e o documento de uma verificação, por URL assinada.

Status de verificação

Os cinco valores e o que cada um significa.