# Como consultar nome completo pelo número do CPF gratuitamente

> Saiba como consultar o nome completo de uma pessoa pelo número do CPF gratuitamente usando a API da CPFHub.io com exemplos práticos.

**Publicado:** 24/05/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-consultar-nome-completo-pelo-numero-do-cpf-gratuitamente

---


Para consultar o nome completo pelo número do CPF gratuitamente, crie uma conta no plano Grátis da CPFHub.io (zero custo, sem cartão de crédito), gere sua chave de API no painel e faça uma requisição GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key`. O campo `name` na resposta JSON retorna o nome completo do titular em menos de 1 segundo.

## Introdução

Uma das necessidades mais comuns de desenvolvedores e empresas no Brasil é descobrir o nome completo associado a um número de CPF. Essa informação é essencial para processos de onboarding, verificação de identidade, emissão de documentos fiscais e prevenção de fraudes.

A [**CPFHub.io**](https://www.cpfhub.io/) oferece 50 consultas gratuitas por mês — sem cartão de crédito — com retorno de nome completo, data de nascimento e gênero do titular, com latência de aproximadamente 900ms e exemplos prontos em diversas linguagens de programação.

---

## Por que consultar o nome pelo CPF

A consulta de nome por CPF atende a diversas necessidades de negócio:

* **Verificação de identidade** -- Confirmar se o nome informado pelo usuário corresponde ao registrado oficialmente.

* **Prevenção de fraudes** -- Detectar inconsistências entre dados fornecidos e dados reais do titular do CPF.

* **Emissão de documentos fiscais** -- Garantir que o nome e CPF do cliente estão corretos antes de emitir notas fiscais.

* **Onboarding de clientes** -- Preencher automaticamente campos de cadastro com dados verificados.

* **Compliance regulatório** -- Atender requisitos de KYC (Know Your Customer) exigidos por reguladores.

---

## Como funciona o plano gratuito da CPFHub.io

O plano Grátis da [**CPFHub.io**](https://www.cpfhub.io/) inclui todas as funcionalidades da API sem custo mensal:

| Recurso | Detalhe |
| --- | --- |
| Preço | R$ 0,00/mês |
| Consultas | 50 por mês |
| Rate limit | 1 requisição a cada 2 segundos |
| Autenticação | Chave de API (x-api-key) |
| Formato de resposta | JSON |
| SLA | 80% |
| Cartão de crédito | Não necessário |

Para começar, basta criar uma conta gratuita em cpfhub.io, gerar uma chave de API no painel de controle (app.cpfhub.io) e fazer sua primeira consulta em menos de 5 minutos.

---

## Dados retornados pela API

Ao consultar um CPF, a API retorna os seguintes campos:

| Campo | Descrição |
| --- | --- |
| cpf | Número do CPF consultado |
| name | Nome completo do titular |
| nameUpper | Nome em letras maiúsculas |
| gender | Gênero (M ou F) |
| birthDate | Data de nascimento (DD/MM/YYYY) |
| day | Dia de nascimento |
| month | Mês de nascimento |
| year | Ano de nascimento |

O campo `name` retorna o nome completo exatamente como registrado, enquanto `nameUpper` retorna a versão em maiúsculas, útil para comparações e padronização.

---

## Consulta via cURL

A forma mais rápida de testar a consulta é usando cURL diretamente no terminal:

```bash
curl -X GET https://api.cpfhub.io/cpf/12345678900 \
 -H "x-api-key: SUA_CHAVE_DE_API" \
 -H "Accept: application/json"
```

A resposta será um JSON como este:

```json
{
 "success": true,
 "data": {
 "cpf": "12345678900",
 "name": "João da Silva",
 "nameUpper": "JOAO DA SILVA",
 "gender": "M",
 "birthDate": "15/06/1990",
 "day": 15,
 "month": 6,
 "year": 1990
 }
}
```

O campo `name` contém exatamente o que você precisa: o nome completo do titular do CPF.

---

## Exemplo em Python

```python
import requests

cpf = "12345678900"
url = f"https://api.cpfhub.io/cpf/{cpf}"
headers = {
 "x-api-key": "SUA_CHAVE_DE_API",
 "Accept": "application/json"
}

response = requests.get(url, headers=headers, timeout=10)

if response.status_code == 200:
 data = response.json()
 if data["success"]:
 nome = data["data"]["name"]
 print(f"Nome completo: {nome}")
 else:
 print("CPF não encontrado.")
elif response.status_code == 401:
 print("Chave de API inválida.")
elif response.status_code == 429:
 print("Rate limit excedido. Aguarde antes de tentar novamente.")
else:
 print(f"Erro: HTTP {response.status_code}")
```

---

## Exemplo em JavaScript (Node.js)

```javascript
const cpf = '12345678900';

async function consultarNomePorCPF(cpf) {
 const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
 method: 'GET',
 headers: {
 'x-api-key': 'SUA_CHAVE_DE_API',
 'Accept': 'application/json'
 },
 timeout: 10000
 });

 if (!response.ok) {
 throw new Error(`Erro HTTP: ${response.status}`);
 }

 const data = await response.json();

 if (data.success) {
 console.log(`Nome completo: ${data.data.name}`);
 return data.data.name;
 } else {
 console.log('CPF não encontrado.');
 return null;
 }
}

consultarNomePorCPF(cpf);
```

---

## Exemplo em PHP

```php
<?php
$cpf = '12345678900';
$curl = curl_init();

curl_setopt_array($curl, [
 CURLOPT_URL => "https://api.cpfhub.io/cpf/{$cpf}",
 CURLOPT_RETURNTRANSFER => true,
 CURLOPT_TIMEOUT => 10,
 CURLOPT_HTTPHEADER => [
 'x-api-key: SUA_CHAVE_DE_API',
 'Accept: application/json'
 ],
]);

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($httpCode === 200) {
 $data = json_decode($response, true);
 if ($data['success']) {
 echo "Nome completo: " . $data['data']['name'];
 } else {
 echo "CPF não encontrado.";
 }
} else {
 echo "Erro: HTTP {$httpCode}";
}
```

---

## Comparação de nome informado vs. nome real

Um caso de uso muito comum é comparar o nome informado pelo usuário com o nome real retornado pela API. Isso é útil para detecção de fraudes e verificação de identidade:

```python
import requests
from difflib import SequenceMatcher

def comparar_nomes(nome_informado, nome_real):
 """Retorna a similaridade entre dois nomes (0 a 1)."""
 nome_informado = nome_informado.upper().strip()
 nome_real = nome_real.upper().strip()
 return SequenceMatcher(None, nome_informado, nome_real).ratio()

def verificar_identidade(cpf, nome_informado, api_key):
 url = f"https://api.cpfhub.io/cpf/{cpf}"
 headers = {
 "x-api-key": api_key,
 "Accept": "application/json"
 }

 response = requests.get(url, headers=headers, timeout=10)
 data = response.json()

 if data["success"]:
 nome_real = data["data"]["nameUpper"]
 similaridade = comparar_nomes(nome_informado, nome_real)

 if similaridade >= 0.85:
 return {"match": True, "similaridade": similaridade}
 else:
 return {"match": False, "similaridade": similaridade}

 return {"error": "CPF não encontrado"}

# Exemplo de uso
resultado = verificar_identidade(
 cpf="12345678900",
 nome_informado="João da Silva",
 api_key="SUA_CHAVE_DE_API"
)
print(resultado)
```

O uso de similaridade em vez de comparação exata permite lidar com pequenas variações de grafia, abreviações ou acentuação.

---

## Dicas para aproveitar ao máximo o plano gratuito

### Valide o CPF localmente antes de consultar

Não desperdice suas 50 consultas mensais com CPFs com formato inválido. Valide os dígitos verificadores antes de chamar a API.

### Cache os resultados

Se você precisa consultar o mesmo CPF mais de uma vez, armazene o resultado em cache local para evitar consultas duplicadas.

### Use o plano gratuito como sandbox

O plano Grátis é ideal para prototipagem e testes de integração. Depois de validar seu fluxo, migre para o plano Pro (R$ 149/mês, 1.000 consultas) para uso em produção.

### Monitore seu consumo

Acompanhe o número de consultas realizadas no dashboard (app.cpfhub.io) para não ultrapassar o limite mensal.

---

## Perguntas frequentes

### O plano gratuito realmente retorna o nome completo pelo CPF?
Sim. O plano Grátis da CPFHub.io retorna os mesmos dados que os planos pagos: nome completo (`name`), nome em maiúsculas (`nameUpper`), gênero, data de nascimento e status do CPF. A única diferença em relação aos planos pagos é o limite de 50 consultas/mês e o rate limit de 1 requisição a cada 2 segundos.

### Quanto tempo leva para obter o nome pelo CPF via API?
A latência média da API é de aproximadamente 900ms. Para aplicações que precisam de resposta em tempo real durante o cadastro, esse tempo é imperceptível para o usuário. Se o tempo de resposta for crítico, utilize a validação local dos dígitos verificadores (instantânea) antes de acionar a consulta remota.

### Posso usar a consulta de nome por CPF para preencher formulários automaticamente?
Sim. Um fluxo comum é: usuário digita o CPF → frontend chama a API → resposta preenche automaticamente o campo de nome completo. Isso reduz erros de digitação e melhora a experiência de onboarding. Certifique-se de informar ao usuário que o dado está sendo preenchido automaticamente a partir do CPF, conforme as boas práticas da [LGPD](https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2018/lei/l13709.htm).

### Como comparar o nome retornado com o nome que o usuário digitou?
Use algoritmos de similaridade de strings, como `SequenceMatcher` (Python) ou `Levenshtein distance` (disponível em praticamente todas as linguagens). Um limiar de 85% de similaridade costuma ser suficiente para aceitar pequenas variações de grafia e abreviações. Nomes com similaridade abaixo de 70% devem acionar uma revisão manual.

### Leia também

- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma)
- [API de consulta de CPF: diferenças entre planos gratuito, Pro e Corporate](https://cpfhub.io/blog/api-de-consulta-de-cpf-diferencas-entre-planos-gratuito-pro-e-corporate)
- [APIs de CPF: como avaliar o custo-benefício antes de contratar?](https://cpfhub.io/blog/apis-de-cpf-como-avaliar-o-custo-beneficio-antes-de-contratar)

---

## Conclusão

Consultar o nome completo pelo número do CPF é uma operação fundamental para inúmeros processos de negócio no Brasil. Com o plano gratuito da [**CPFHub.io**](https://www.cpfhub.io/), qualquer desenvolvedor pode começar a usar a API em minutos, sem burocracia e sem custo inicial.

A API é simples de integrar, com suporte a mais de 13 linguagens de programação, documentação completa e tempo de resposta de aproximadamente 900ms. Para volumes maiores, os planos Pro e Corporativo oferecem limites ampliados e suporte prioritário.

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e consulte seu primeiro nome pelo CPF hoje mesmo.