# Leads por Endereço

> Lista os registros de pessoas e empresas associados a um endereço, a partir do CEP e do número. Use para prospecção e para descobrir quem está ligado a um imóvel.

- **Consulta:** `leads-endereco`
- **Categoria:** Comercial
- **Preço:** R$ 1,33 por consulta
- **Endpoint:** `POST https://app.fontedata.com/api/v1/consulta/leads-endereco`
- **Autenticação:** header `X-API-Key`
- **Página:** https://fontedata.com/docs/comercial/leads-endereco

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> Lista as pessoas físicas e empresas associadas a um endereço. A busca parte do CEP; ao informar também o número do imóvel, o resultado se restringe àquele endereço em vez de trazer todo o CEP — o que, em ruas longas, é a diferença entre dezenas e milhares de registros.
>
> Telefones e e-mails não vêm aqui: para obtê-los, use o endpoint **Contato do Lead** passando o `id` de cada registro (lead) desta lista — assim você paga o contato apenas de quem interessa.

## Requisição

### cURL

```bash
curl -X POST -H "X-API-Key: SUA_CHAVE" \
  "https://app.fontedata.com/api/v1/consulta/leads-endereco?cep=04530-060&numero=109"
```

### Python

```python
import requests

resp = requests.post(
    "https://app.fontedata.com/api/v1/consulta/leads-endereco",
    params={"cep": "04530-060", "numero": "109"},
    headers={"X-API-Key": "SUA_CHAVE"},
    timeout=60,
)
resp.raise_for_status()
print(resp.json())
```

### Node.js

```javascript
const url = new URL("https://app.fontedata.com/api/v1/consulta/leads-endereco");

url.search = new URLSearchParams({
  "cep": "04530-060",
  "numero": "109"
}).toString();

const resp = await fetch(url, {
  method: "POST",
  headers: { "X-API-Key": "SUA_CHAVE" }
});

if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());
```

## Parâmetros

| Nome | Tipo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|---|
| `cep` | texto | sim | CEP do endereço, com ou sem hífen (ex.: 11700-200 ou 11700200). | `04530-060` |
| `numero` | texto | não | Número do imóvel. Sem ele a busca devolve todo o CEP, que pode cobrir a rua inteira — informe o número para restringir ao endereço. | `109` |
| `tipo_pessoa` | texto | não | Filtra o resultado: PF (pessoas físicas) ou PJ (empresas). Sem o filtro, retorna os dois. | — |

## Resposta

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> - **`enderecoConsultado`**: eco do CEP, número e filtro usados na busca.
> - **`totalLeads`**: total de registros localizados. Com o número informado, refere-se ao endereço; sem ele, ao CEP inteiro.
> - **`totalPessoasFisicas`** e **`totalPessoasJuridicas`**: a divisão do total entre pessoas e empresas.
> - **`leads[]`**: **todos** os registros contados em `totalLeads` — a lista não é truncada nem paginada. Cada um traz:
>   - `id` — identificador do registro; informe-o na consulta Contato do Lead.
>   - `nome` — **razão social completa** quando é empresa; nome **parcialmente mascarado** quando é pessoa física.
>   - `documento` — **CNPJ completo** quando é empresa; **CPF parcialmente mascarado** quando é pessoa física.
>   - `tipoPessoa` — `PF` ou `PJ`.
>   - `cnae` — atividade principal, quando o registro é empresa.
>
> Quando o endereço não tem nenhum registro, a resposta vem com `consta: false` e **é cobrada normalmente** — a consulta foi executada na base de origem.

### Exemplo de resposta

```json
{
  "leads": [
    {
      "id": "48282358",
      "cnae": "8112500",
      "nome": "CONDOMINIO EDIFICIO EXEMPLO",
      "documento": "00000000000191",
      "tipoPessoa": "PJ"
    },
    {
      "id": "77158934",
      "cnae": null,
      "nome": "LIA ****** *******",
      "documento": "106***538**",
      "tipoPessoa": "PF"
    }
  ],
  "totalLeads": 188,
  "enderecoConsultado": {
    "cep": "04530060",
    "numero": "109",
    "tipoPessoa": null
  },
  "totalPessoasFisicas": 179,
  "totalPessoasJuridicas": 9
}
```

### Schema da resposta

```json
{
  "type": "object",
  "properties": {
    "leads": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "string",
              "integer",
              "null"
            ],
            "description": "Identificador do registro na base de origem. Informe-o no parâmetro `id` da consulta Contato do Lead. Use na sequência da busca — não é um identificador permanente."
          },
          "cnae": {
            "type": [
              "string",
              "integer",
              "null"
            ],
            "description": "Código CNAE da atividade principal, quando o registro é empresa. Nulo para pessoa física."
          },
          "nome": {
            "type": [
              "string",
              "null"
            ],
            "description": "Razão social completa quando o registro é empresa; nome parcialmente mascarado quando é pessoa física."
          },
          "documento": {
            "type": [
              "string",
              "null"
            ],
            "description": "CNPJ completo quando o registro é empresa; CPF parcialmente mascarado quando é pessoa física."
          },
          "tipoPessoa": {
            "type": [
              "string",
              "null"
            ],
            "description": "PF para pessoa física, PJ para empresa."
          }
        }
      },
      "x-display": "table",
      "description": "Todos os registros contados em `totalLeads` — a lista não é truncada nem paginada. Para obter telefone e e-mail, use o `id` na consulta Contato do Lead."
    },
    "totalLeads": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Total de registros localizados. Quando o número do imóvel é informado, refere-se ao endereço; sem ele, ao CEP inteiro — que pode cobrir a rua toda."
    },
    "enderecoConsultado": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "cep": {
          "type": [
            "string",
            "null"
          ],
          "description": "CEP consultado, somente dígitos."
        },
        "numero": {
          "type": [
            "string",
            "null"
          ],
          "description": "Número do imóvel, quando informado."
        },
        "tipoPessoa": {
          "type": [
            "string",
            "null"
          ],
          "description": "Filtro aplicado (PF ou PJ), quando informado."
        }
      },
      "description": "Eco dos parâmetros usados na busca."
    },
    "totalPessoasFisicas": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Quantos dos registros são pessoas físicas."
    },
    "totalPessoasJuridicas": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Quantos dos registros são empresas."
    }
  }
}
```

## Códigos de erro

| Código | Mensagem | Quando acontece |
|---|---|---|
| `400` | Parâmetro inválido. Verifique o CEP (00000-000 ou 00000000), o número do imóvel e o tipo de pessoa (PF ou PJ). | O `cep`, o `numero` ou o `tipo_pessoa` enviado não bate com o formato esperado. |
| `402` | Saldo insuficiente para realizar a consulta. | A conta não tem saldo para cobrir o preço da consulta. |
| `504` | A consulta excedeu o tempo limite. Tente novamente. | A base de origem não respondeu dentro do tempo limite. |
| `503` | Serviço de consulta temporariamente indisponível. Tente novamente. | A base de origem não respondeu ou devolveu erro transitório. |

## Quando usar

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> - Prospecção imobiliária e comercial a partir de um endereço ou de uma região.
> - Descobrir quem está associado a um imóvel específico antes de uma abordagem. Empresas e condomínios saem identificados por completo, com CNPJ — dá para cruzar com as consultas de CNPJ do catálogo.
> - Dimensionar o potencial de um endereço antes de investir em contatos: a lista mostra quantos registros existem, e você decide de quantos quer o contato.
>
> **Importante:** os registros refletem quem consta associado ao endereço nas bases consultadas — moradores atuais, anteriores e empresas ali sediadas. A consulta não distingue proprietário de inquilino nem informa desde quando o vínculo existe. O `id` serve para a consulta de contato logo em seguida; não o armazene como identificador permanente.

---

Página em HTML: https://fontedata.com/docs/comercial/leads-endereco
Catálogo completo: https://fontedata.com/docs
OpenAPI (JSON): https://app.fontedata.com/api/v1/openapi.json
Conectar via MCP: https://fontedata.com/docs/mcp