cpfhub
Official Ruby SDK for CPFHub.io — Brazilian CPF Lookup API
SDK oficial Ruby 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
gem install cpfhubOr in your Gemfile:
gem 'cpfhub'Quick Start
require 'cpfhub'
client = CPFHub::Client.new(api_key: ENV['CPFHUB_API_KEY'])
result = client.lookup('00000000000')
puts result.name # "Fulano de Tal"
puts result.gender # "M"
puts 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.
API Reference
CPFHub::Client.new(api_key:, timeout: 10, base_url: nil)
| Option | Type | Default | Description |
|---|---|---|---|
api_key |
String |
required | Your CPFHub API key |
timeout |
Integer |
10 |
Request timeout in seconds |
base_url |
String |
https://api.cpfhub.io |
API base URL |
client.lookup(cpf) → CPFHub::Result
Accepts CPF with or without formatting (000.000.000-00 or 00000000000).
CPFHub::Result attributes
| Attribute | Type | Description |
|---|---|---|
cpf |
String |
CPF number (digits only) |
name |
String |
Full name — "Fulano de Tal"
|
name_upper |
String |
Full name in uppercase |
gender |
String |
"M" or "F"
|
birth_date |
String |
Date of birth — "DD/MM/YYYY"
|
day |
Integer |
Birth day |
month |
Integer |
Birth month |
year |
Integer |
Birth year |
Error Handling
require 'cpfhub'
client = CPFHub::Client.new(api_key: ENV['CPFHUB_API_KEY'])
begin
result = client.lookup('00000000000')
puts result.name
rescue CPFHub::Error => e
puts "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
endExamples
Ruby (plain)
require 'cpfhub'
client = CPFHub::Client.new(api_key: ENV['CPFHUB_API_KEY'], timeout: 5)
result = client.lookup('00000000000')
puts result.nameRuby on Rails
# config/initializers/cpfhub.rb
CPFHub.configure do |config|
config.api_key = Rails.application.credentials.cpfhub_api_key
end# app/services/cpf_lookup_service.rb
class CpfLookupService
def self.call(cpf)
CPFHub::Client.new(api_key: Rails.application.credentials.cpfhub_api_key)
.lookup(cpf)
end
end# app/controllers/onboarding_controller.rb
class OnboardingController < ApplicationController
def verify
result = CpfLookupService.call(params[:cpf])
render json: { name: result.name, gender: result.gender }
end
endSidekiq (background job)
class CpfVerificationWorker
include Sidekiq::Worker
def perform(user_id, cpf)
client = CPFHub::Client.new(api_key: ENV['CPFHUB_API_KEY'])
result = client.lookup(cpf)
User.find(user_id).update!(verified_name: result.name)
end
endRate 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).
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
- Ruby 3.0+
Links
License / Licença
MIT © CPFHub.io