Verificação de Identidade

Crie um link de verificação, envie para a pessoa e receba a decisão. A página da verificação, hospedada pela CPFHub.io, faz a prova de vida, lê o documento (CNH, RG ou passaporte), compara o rosto com a foto do documento e confere o CPF na Receita Federal. Custa 5 créditos por verificação concluída.

Usando Cursor, Lovable, v0 ou outra IA? Copie o prompt da Verificação de Identidade e cole no seu assistente.

Abrir no Cursor

Usando Cursor, Lovable, v0 ou outra IA? Copie o prompt da Verificação de Identidade e cole no seu assistente.

Abrir no Cursor

POST /kyc/links cria o link e devolve a url.
Você envia a url para a pessoa ou redireciona para ela no seu cadastro.
A decisão chega no seu webhook, ou pela consulta GET /kyc/links/{id}.

A verificação não valida o documento em base do governo, não faz perícia documental e não aceita CNH Digital.

Criar link

POSThttps://api.cpfhub.io/kyc/links

Onde	Nome	Obrigatório	Descrição
Header	`x-api-key`	Sim	Sua API Key, a mesma das consultas
Body	`externalId`	Não	O seu identificador do cadastro (até 200 caracteres). Volta no webhook.
Body	`cpf`	Não	CPF que você já conhece. Se divergir do documento, a verificação vai para revisão. Nunca volta nas respostas.
Body	`redirectUrl`	Não	Para onde a pessoa volta ao terminar. Só `https`.
Body	`language`	Não	`pt-BR`, `en` ou `es`. Padrão: idioma do navegador.
Body	`expiresInMinutes`	Não	Validade, de `5` a `10080`. Padrão: `1440` (24 h).
Body	`maxAttempts`	Não	Tentativas, de `1` a `10`. Padrão: `3`.

curl -X POST "https://api.cpfhub.io/kyc/links" \
  -H "x-api-key: $CPFHUB_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "externalId": "cliente-4821",
    "redirectUrl": "https://seusite.com.br/cadastro/concluido"
  }'

HTTP 201 Created

JSON

{
  "success": true,
  "data": {
    "id": "5b1d7c2e-8a4f-4e7b-9c3d-2f6a1e0b9d47",
    "url": "https://verificar.cpfhub.io/AbC123xYz",
    "externalId": "cliente-4821",
    "expiresAt": "2026-10-28T14:00:00.000Z",
    "maxAttempts": 3,
    "language": null
  }
}

Guarde o id: ele volta no webhook como linkId. Ao terminar, a pessoa volta para redirectUrl com kyc_link_id e external_id na URL, mas sem a decisão: confirme pelo webhook ou pela consulta.

Consultar link

GEThttps://api.cpfhub.io/kyc/links/{id}

JSON

{
  "success": true,
  "data": {
    "id": "5b1d7c2e-8a4f-4e7b-9c3d-2f6a1e0b9d47",
    "url": null,
    "externalId": "cliente-4821",
    "status": "completed",
    "attempts": 1,
    "maxAttempts": 3,
    "expiresAt": "2026-10-28T14:00:00.000Z",
    "createdAt": "2026-10-27T14:00:00.000Z",
    "completedAt": "2026-10-27T14:06:12.000Z",
    "verification": {
      "id": "8f3c2a1e-77b0-4d3c-9a1f-0e5b6c7d8e9f",
      "status": "approved",
      "reasons": [],
      "completedAt": "2026-10-27T14:06:12.000Z"
    }
  }
}

status do link: pending, completed, expired ou canceled. url volta só enquanto o link pode ser usado. verification é null até a pessoa terminar. Sem dados pessoais.

Decisão

`verification.status`	Significado
`approved`	Tudo certo. O link é encerrado.
`manual_review`	Precisa de uma pessoa da sua equipe (veja `reasons`). Revise no painel. O link é encerrado.
`rejected`	Reprovada pelas regras da conta. A pessoa pode tentar de novo enquanto houver tentativas.

Os motivos vêm em reasons como [{ "code", "message" }]. Os mais comuns: face_similarity_borderline, document_expired, ocr_failed, cpf_document_mismatch, cpf_name_mismatch e cpf_situation_irregular. Trate um code desconhecido como revisão e mostre o message só para a sua equipe.

Configurações

Documentos aceitos, limites de semelhança facial, revisão manual, documento vencido, marca, retenção e o webhook ficam no painel, em Verificações > Configurações, e valem para todos os links da conta.

Erros

Status	Quando acontece	O que fazer
`400`	Parâmetro inválido (`redirectUrl` sem `https`, `cpf` inválido, valor fora do permitido)	Corrija o body. Não repita.
`401`	API Key ausente, inválida ou inativa	Confira o header `x-api-key`.
`403`	Conta inativa ou bloqueada	Fale com o suporte.
`404`	Link não existe ou é de outra API Key	Confira o `id`.
`503`	Falha passageira	Repita com espera crescente (2 s, 4 s, 8 s).

Formato do erro: Códigos de Erro.

Custo

5 créditos por verificação concluída, do mesmo saldo das consultas, inclusive quando é reprovada. Já inclui o cruzamento do CPF. Criar e consultar links não custa nada, e falha técnica nossa não cobra.

⚠

O link dá acesso à verificação

Quem tiver a url pode fazer a verificação no lugar da pessoa. Crie um link por pessoa, envie só para ela e use a validade e as tentativas mais curtas que o seu fluxo permitir.

Atualizado em 27 de outubro de 2026