Documentação da API LeadCNPJ

Endpoints · Empresas

Busca avançada de empresas por filtros firmográficos

Mesma engine da busca avançada do app. Filtros: UF, município, CNAE, porte, capital social, idade da empresa, presença de e-mail/telefone/WhatsApp, situação cadastral, regime tributário. Paginada (max 100/página). Custa 1 consulta por CNPJ retornado (0,5 crédito nos planos com API).

Mínimo de 3 filtros ativos por request (controle de uso justo). Combine pelo menos UF + CNAE + outro (porte, idade, capital, etc.). Request com menos de 3 filtros retorna 422 validation_error.

Default de situação cadastral: situacao_ativa=true é aplicado por padrão. Para incluir Baixadas/Suspensas/Inaptas/Nulas, envie situacao_ativa=false explicitamente.

Parâmetros

Nome	Em	Obrigatório	Descrição
Idempotency-Key	header	não	Identificador único da requisição (sugestão: UUID v4 ou ULID gerado pelo cliente). Se a mesma key for reenviada com mesmo body em até 24h, a API retorna a resposta cacheada da primeira chamada com header `Idempotency-Replayed: true`. Reuso com body diferente → 409 idempotency_conflict.

Body da requisição

Campo	Tipo	Descrição
uf	string	Ex: SP
municipio	array<string>
cnae	array<string>
porte	array<string>
natureza_juridica	string
capital_social_de	number
capital_social_ate	number
idade_minima	integer	Idade mínima da empresa em anos.
idade_maxima	integer
email	boolean	Apenas com e-mail cadastrado.
email_corporativo	boolean	Exclui e-mails de gmail/hotmail/etc.
ignorar_contabilidade	boolean	Exclui e-mails de escritórios contábeis.
telefone	boolean
whatsapp	boolean
situacao_ativa	boolean	Filtra apenas empresas com situação cadastral Ativa (código 02). Default true — passe false explicitamente para incluir Baixadas/Suspensas/Inaptas/Nulas.
somente_matriz	boolean
mei	boolean
simples_nacional	boolean
ignorar_mei_simples	boolean
empresa_nova	boolean	Apenas empresas abertas há ≤6 meses.
page	integer
per_page	integer

Exemplo:

{
    "uf": "SP",
    "cnae": [
        "4330401",
        "4330404"
    ],
    "porte": [
        "01",
        "03"
    ],
    "capital_social_de": 50000,
    "email_corporativo": true,
    "ignorar_contabilidade": true,
    "situacao_ativa": true,
    "page": 1,
    "per_page": 25
}

Respostas

Status	Descrição
200	Lista paginada de empresas.
401	Token ausente, inválido ou revogado.
402	Créditos insuficientes pra completar a operação.
403	Plano não permite uso da API ou escopo insuficiente.
422	Body ou query params inválidos.
429	Excedeu o rate limit. Veja header Retry-After.
409	Idempotency-Key já foi usada em até 24h com um corpo de requisição diferente. Errors codes possíveis: `idempotency_conflict` (mesma key, body diferente), `idempotency_in_progress` (outra request com a mesma key ainda processando — Retry-After=1).

Exemplo curl

curl -X POST https://leadcnpj.com.br/api/v1/empresas/buscar \
  -H "Authorization: Bearer leadcnpj_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"uf":"SP","cnae":["4330401","4330404"],"porte":["01","03"],"capital_social_de":50000,"email_corporativo":true,"ignorar_contabilidade":true,"situacao_ativa":true,"page":1,"per_page":25}'