Verificación de Identidad

Crea un enlace de verificación, envíalo a la persona y recibe la decisión. La página de la verificación, alojada por CPFHub.io, hace la prueba de vida, lee el documento (CNH, RG o pasaporte), compara el rostro con la foto del documento y coteja el CPF con la Receita Federal. Cuesta 5 créditos por verificación completada.

¿Usas Cursor, Lovable, v0 u otra IA? Copia el prompt de la Verificación de Identidad y pégalo en tu asistente.

Abrir en Cursor

¿Usas Cursor, Lovable, v0 u otra IA? Copia el prompt de la Verificación de Identidad y pégalo en tu asistente.

Abrir en Cursor

POST /kyc/links crea el enlace y devuelve la url.
Envías la url a la persona o la rediriges a ella en tu registro.
La decisión llega a tu webhook, o por la consulta GET /kyc/links/{id}.

La verificación no valida el documento en una base del gobierno, no hace peritaje documental y no acepta la CNH Digital.

Crear enlace

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

Dónde	Nombre	Obligatorio	Descripción
Header	`x-api-key`	Sí	Tu API Key, la misma de las consultas
Body	`externalId`	No	Tu identificador del registro (hasta 200 caracteres). Vuelve en el webhook.
Body	`cpf`	No	CPF que ya conoces. Si difiere del documento, la verificación pasa a revisión. Nunca vuelve en las respuestas.
Body	`redirectUrl`	No	Adónde vuelve la persona al terminar. Solo `https`.
Body	`language`	No	`pt-BR`, `en` o `es`. Por defecto: idioma del navegador.
Body	`expiresInMinutes`	No	Validez, de `5` a `10080`. Por defecto: `1440` (24 h).
Body	`maxAttempts`	No	Intentos, de `1` a `10`. Por defecto: `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
  }
}

Guarda el id: vuelve en el webhook como linkId. Al terminar, la persona vuelve a redirectUrl con kyc_link_id y external_id en la URL, pero sin la decisión: confírmala por el webhook o por la consulta.

Consultar enlace

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 del enlace: pending, completed, expired o canceled. url vuelve solo mientras el enlace se puede usar. verification es null hasta que la persona termine. Sin datos personales.

Decisión

`verification.status`	Significado
`approved`	Todo en orden. El enlace se cierra.
`manual_review`	Necesita a alguien de tu equipo (ver `reasons`). Revísalo en el dashboard. El enlace se cierra.
`rejected`	Rechazada por las reglas de la cuenta. La persona puede intentarlo de nuevo mientras queden intentos.

Los motivos llegan en reasons como [{ "code", "message" }]. Los más comunes: face_similarity_borderline, document_expired, ocr_failed, cpf_document_mismatch, cpf_name_mismatch y cpf_situation_irregular. Trata un code desconocido como revisión y muestra el message solo a tu equipo.

Configuración

Los documentos aceptados, los límites de similitud facial, la revisión manual, el documento vencido, la marca, la retención y el webhook están en el dashboard, en Verificações > Configurações, y valen para todos los enlaces de la cuenta.

Errores

Status	Cuándo ocurre	Qué hacer
`400`	Parámetro inválido (`redirectUrl` sin `https`, `cpf` inválido, valor fuera de lo permitido)	Corrige el body. No repitas.
`401`	API Key ausente, inválida o inactiva	Revisa el header `x-api-key`.
`403`	Cuenta inactiva o bloqueada	Habla con soporte.
`404`	El enlace no existe o es de otra API Key	Revisa el `id`.
`503`	Falla pasajera	Repite con esperas crecientes (2 s, 4 s, 8 s).

Formato del error: Códigos de Error.

Costo

5 créditos por verificación completada, del mismo saldo de las consultas, incluso cuando es rechazada. Ya incluye el cruce del CPF. Crear y consultar enlaces no cuesta nada, y una falla técnica nuestra no se cobra.

⚠

El enlace da acceso a la verificación

Quien tenga la url puede hacer la verificación en lugar de la persona. Crea un enlace por persona, envíalo solo a ella y usa la validez y los intentos más cortos que tu flujo permita.

Actualizado el 27 de octubre de 2026