Consulta Simple

Envía el CPF (el número de identificación fiscal de personas físicas en Brasil) y recibe el nombre, el género y la fecha de nacimiento desde la base de datos de CPFHub.io. Cuesta 1 crédito por CPF encontrado.

¿Usas Cursor, Lovable, v0 u otra IA? Copia el prompt de la Consulta Simple y pégalo en tu asistente.

Abrir en Cursor

¿Usas Cursor, Lovable, v0 u otra IA? Copia el prompt de la Consulta Simple y pégalo en tu asistente.

Abrir en Cursor

¿No es esta? Compara las consultas.

Endpoint

GEThttps://api.cpfhub.io/cpf/{cpf}

Parámetros

Dónde	Nombre	Obligatorio	Descripción
Path	`cpf`	Sí	CPF con o sin formato: `12345678909` o `123.456.789-09`
Header	`x-api-key`	Sí	Tu clave de API. Consulta Autenticación.

Ejemplo

Los ejemplos leen la clave desde CPFHUB_API_KEY, tratan el 404 como un resultado normal y usan un timeout de 10 s. Otros lenguajes: Ejemplos por lenguaje.

curl --max-time 10 "https://api.cpfhub.io/cpf/12345678909" \
  -H "x-api-key: $CPFHUB_API_KEY"

Respuesta

HTTP 200 OK

JSON

{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "Fulano de Tal",
    "nameUpper": "FULANO DE TAL",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
  }
}

Campo	Tipo	Descripción
`data.cpf`	`string`	CPF consultado, 11 dígitos sin formato
`data.name`	`string`	Nombre completo. Puede venir en mayúsculas, así que para comparar usa `nameUpper`
`data.nameUpper`	`string`	Nombre completo en mayúsculas
`data.gender`	`"M"` \| `"F"` \| `null`	Género. `null` cuando la base de datos no tiene la información
`data.birthDate`	`string`	Fecha de nacimiento, `DD/MM/AAAA`
`data.day`, `data.month`, `data.year`	`number`	Componentes de la fecha de nacimiento

Errores

La API responde solo en portugués. Los mensajes de error se muestran tal como llegan, con la traducción entre paréntesis la primera vez.

Estado	Cuándo ocurre	Qué hacer
`400`	CPF sin 11 dígitos	Corrige el CPF. No repitas.
`401`	Clave de API ausente, inválida o inactiva (`error` es una cadena)	Revisa el header `x-api-key`.
`403`	Créditos agotados sin excedente (`error.message`: `"Limite de créditos excedido"`, límite de créditos excedido) o cuenta inactiva/bloqueada (`error` es una cadena)	Recarga créditos o contacta a soporte. No repitas.
`404`	CPF no encontrado en la base de datos	Resultado normal. No consume crédito.
`422`	Dígito verificador incorrecto	Corrige el CPF. No repitas.
`429`	Límite por minuto excedido (30/min por defecto)	Espera los segundos indicados en el header `Retry-After`. No consume crédito.
`500`, `503`	Falla pasajera	Repite con esperas crecientes (2 s, 4 s, 8 s). No consume crédito.

Formato del error, reintentos y cómo probar sin gastar créditos: Códigos de Error. Límite por minuto y créditos: Límites de Uso.

Detalles

Costo: 1 crédito por CPF encontrado (200). Algunos planes tienen un costo propio, así que consulta el de tu plan en el dashboard.
Tiempo de respuesta: típico de ~150 ms (no es un SLA). Usa un timeout de unos 10 s.
Timeout del cliente: la consulta pudo completarse y cobrarse en el servidor. Si repites, se cobra de nuevo.
Datos de ejemplo: el CPF 12345678909 y los datos anteriores son ficticios.

Actualizado el 4 de octubre de 2026