Official Python SDK for CPFHub.io — Brazilian CPF Lookup API
SDK oficial Python para a CPFHub.io — API de consulta de CPF
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
pip install cpfhubfrom 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.
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())| 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 |
Looks up a CPF and returns the associated data.
Accepts CPF with or without formatting (000.000.000-00 or 00000000000).
| 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 |
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 unavailablefrom cpfhub import CPFHub
client = CPFHub(api_key="YOUR_API_KEY", timeout=5)
result = client.lookup("00000000000")
print(result.name)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)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}# 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})| 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
429com backoff exponencial (até 3 tentativas).
| 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 →
- Python 3.8+
requests(sync) orhttpx(async) — installed automatically
MIT © CPFHub.io