cpfhub

Official Python SDK for CPFHub.io — Brazilian CPF Lookup API

SDK oficial Python para a CPFHub.io — API de consulta de CPF

---

What is CPFHub.io?

CPFHub.io is a REST API that returns name, gender, and date of birth from any Brazilian CPF number — in ~300ms, with 99.9% uptime, and full LGPD compliance.

CPFHub.io é uma API REST que retorna nome, gênero e data de nascimento a partir de qualquer CPF brasileiro — em ~300ms, com 99,9% de uptime e total conformidade com a LGPD.

10M+ CPFs queried · 1,300+ active companies · 99.9% uptime

---

Installation / Instalação

pip install cpfhub

---

Quick Start

from cpfhub import CPFHub

client = CPFHub(api_key="YOUR_API_KEY")

result = client.lookup("00000000000")

print(result.name)       # "Fulano de Tal"
print(result.gender)     # "M"
print(result.birth_date) # "15/06/1990"

Get your free API key at app.cpfhub.io — no credit card required.

Obtenha sua chave gratuita em app.cpfhub.io — sem cartão de crédito.

---

Async Support

import asyncio
from cpfhub import AsyncCPFHub

async def main():
    client = AsyncCPFHub(api_key="YOUR_API_KEY")
    result = await client.lookup("00000000000")
    print(result.name)

asyncio.run(main())

---

API Reference

CPFHub(api_key, timeout=10, base_url=None)

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	Your CPFHub API key
timeout	int	No	10	Request timeout in seconds
base_url	str	No	https://api.cpfhub.io	API base URL

client.lookup(cpf: str) -> CPFResult

Looks up a CPF and returns the associated data.

Accepts CPF with or without formatting (000.000.000-00 or 00000000000).

CPFResult attributes

Attribute	Type	Description
cpf	str	CPF number (digits only)
name	str	Full name — "Fulano de Tal"
name_upper	str	Full name in uppercase
gender	str	"M" or "F"
birth_date	str	Date of birth — "DD/MM/YYYY"
day	int	Birth day
month	int	Birth month
year	int	Birth year

---

Error Handling

from cpfhub import CPFHub, CPFHubError

client = CPFHub(api_key="YOUR_API_KEY")

try:
    result = client.lookup("00000000000")
    print(result.name)
except CPFHubError as e:
    print(f"Error {e.status_code}: {e.message}")
    # 400 — Invalid CPF format
    # 401 — Invalid or missing API key
    # 404 — CPF not found
    # 429 — Rate limit exceeded
    # 500 — Server error
    # 503 — Service temporarily unavailable

---

Examples

requests (sync)

from cpfhub import CPFHub

client = CPFHub(api_key="YOUR_API_KEY", timeout=5)
result = client.lookup("00000000000")
print(result.name)

httpx (async)

import asyncio
from cpfhub import AsyncCPFHub

async def verify_cpf(cpf: str):
    client = AsyncCPFHub(api_key="YOUR_API_KEY")
    return await client.lookup(cpf)

result = asyncio.run(verify_cpf("00000000000"))
print(result.name)

FastAPI

from fastapi import FastAPI
from cpfhub import AsyncCPFHub

app = FastAPI()
client = AsyncCPFHub(api_key="YOUR_API_KEY")

@app.get("/cpf/{cpf}")
async def lookup_cpf(cpf: str):
    result = await client.lookup(cpf)
    return {"name": result.name, "gender": result.gender}

Django

# views.py
from django.http import JsonResponse
from cpfhub import CPFHub

client = CPFHub(api_key="YOUR_API_KEY")

def lookup_cpf(request, cpf):
    result = client.lookup(cpf)
    return JsonResponse({"name": result.name, "gender": result.gender})

---

Rate Limits / Limites de Requisição

Plan / Plano	Limit / Limite
Free / Grátis	1 request every 2 seconds · 50 requests/month
Pro	1 request per second · 1,000 requests/month
Corporate / Corporativo	Custom / Personalizado

The SDK automatically retries on 429 with exponential backoff (up to 3 attempts).

O SDK faz retry automático em 429 com backoff exponencial (até 3 tentativas).

---

Plans & Pricing / Planos e Preços

Plan	Price	Included	Extra
Free	R$ 0/month	50 lookups	—
Pro	R$ 149/month	1,000 lookups	R$ 0,15/lookup
Corporate	Custom	Custom	Custom

View full pricing at cpfhub.io →

---

Requirements / Requisitos

• Python 3.8+
• requests (sync) or httpx (async) — installed automatically

---

Links

• Documentation / Documentação
• Dashboard / Painel
• Status Page
• Pricing / Preços
• LGPD Compliance

---

License / Licença

MIT © CPFHub.io