---
title: "Consulta de CPF (lookups.cpf) no SDK Python da NFE.io"
description: "Consulte a situação cadastral de uma pessoa física na Receita Federal por CPF e data de nascimento com client.lookups.cpf."
source_url: https://nfe.io/docs/desenvolvedores/bibliotecas/python/recursos/consulta-cpf/
product: bibliotecas
last_updated: 2026-10-14
tags: ["python", "referencia", "consulta"]
integration: ["sdk"]
---

# Consulta de CPF (`lookups.cpf`)

`client.lookups.cpf` consulta a situação cadastral de uma pessoa física pela
[API de Consulta de CPF](/desenvolvedores/rest-api/consulta-de-cpf-v1), em
`https://naturalperson.api.nfe.io`. A consulta exige o CPF **e a data de nascimento**.

:::note Use a `data_api_key`
As consultas usam a chave de dados (`data_api_key` ou `NFE_DATA_API_KEY`). Veja
[Configuração](../configuration.md).
:::

## Método

```python
lookups.cpf(cpf, birth_date, *, options=None) -> NaturalPerson
```

## Exemplo

```python
from datetime import date

from nfeio import NfeClient, NotFoundError

client = NfeClient()

try:
    pessoa = client.lookups.cpf("529.982.247-25", date(1990, 1, 31))  # ou "1990-01-31"
except NotFoundError:
    print("CPF e data de nascimento não conferem")
else:
    print(pessoa["name"], pessoa.status)
    print(pessoa.federal_tax_number, pessoa.birth_on)  # "52998224725", datetime
```

- `birth_date` aceita `date`, `datetime` (só a data é usada) ou texto `"AAAA-MM-DD"`.
- **CPF e data que não conferem voltam como `NotFoundError`**, e não como erro de validação: é assim
  que a API responde quando a combinação não existe.
- Propriedades tipadas de `NaturalPerson`: `federal_tax_number` (11 posições, como `str`), `status`
  e `birth_on`. O nome e os demais campos ficam no acesso por chave.

## Validação local

O CPF tem os dígitos verificadores conferidos e a data tem o formato conferido antes da requisição.
Um valor inválido levanta `InvalidParameterError`, sem cobrança:

```python
from nfeio import InvalidParameterError, NfeClient

client = NfeClient(api_key="chave-de-exemplo", data_api_key="chave-de-dados-de-exemplo")

for cpf, nascimento in [("111.111.111-11", "1990-01-31"), ("529.982.247-25", "31/01/1990")]:
    try:
        client.lookups.cpf(cpf, nascimento)
    except InvalidParameterError as erro:
        print(erro.param, "-", erro)
```

## Veja também

- [Consulta de CNPJ](./legal-entity-lookup.md) e [Consulta de CEP](./addresses.md).