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 cpfhub

Or 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
end

---

Examples

Ruby (plain)

require 'cpfhub'

client = CPFHub::Client.new(api_key: ENV['CPFHUB_API_KEY'], timeout: 5)
result = client.lookup('00000000000')
puts result.name

Ruby 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
end

Sidekiq (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
end

---

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).

---

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

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

---

License / Licença

MIT © CPFHub.io