# CNPJ Brasil Lookup — Receita Federal company data in bulk (`talesferraz/cnpj-brasil-lookup`) Actor

Look up thousands of Brazilian CNPJs and get Receita Federal registry data: legal name, status, CNAE, address, phone, email, Simples/MEI, size, capital. Pay only for found records.

- **URL**: https://apify.com/talesferraz/cnpj-brasil-lookup.md
- **Developed by:** [Tales Ferraz](https://apify.com/talesferraz) (community)
- **Categories:** Lead generation, Business, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.00 / 1,000 company record founds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## CNPJ Brasil Lookup — Consulta CNPJ em lote (Receita Federal)

Transforme uma lista de CNPJs em registros de empresa limpos, a partir dos dados abertos da Receita
Federal: razão social, nome fantasia, situação cadastral, CNAE principal e secundários, endereço
completo com código IBGE do município, telefone e e-mail da empresa (quando constam no cadastro),
Simples Nacional e MEI, porte, capital social, data de abertura e se é matriz ou filial. Cole 1 ou
100.000 CNPJs e receba um dataset exportável em JSON, CSV ou Excel, ou leia direto por código e por
agentes de IA.

**Você paga só pelos registros encontrados.** CNPJ com dígito verificador inválido ou ausente do
cadastro não custa nada e aparece no resumo para você reconciliar a lista. Sem taxa de início.

### Por que este Actor

- **Confiável**: fonte primária em dados abertos (minhareceita.org, espelho dos dumps da Receita
  Federal) com retentativa automática, e uma segunda fonte (BrasilAPI) como fallback. Uma falha
  passageira não derruba a execução: todo CNPJ recebe um status (`ok`, `not_found`, `error`).
- **Rápido**: 20 consultas em paralelo por padrão, ~1.000 CNPJs por minuto. Dá para subir
  `maxConcurrency` até 50.
- **Completo**: 40+ campos por empresa, incluindo CNAEs secundários, datas de opção pelo
  Simples/MEI e regime tributário anual opcional.
- **Retomável**: o progresso é salvo a cada lote; uma execução abortada ou reiniciada continua de
  onde parou, sem cobrar de novo pelo que já foi encontrado.
- **Privacidade por padrão**: só sai dado de empresa. O quadro de sócios (QSA) é opcional e vem
  exatamente como o governo publica, com o CPF já mascarado na origem — nada é enriquecido ou
  desmascarado por este Actor.

### Entrada

| Campo | Tipo | Padrão | Observação |
|---|---|---|---|
| `cnpjs` | lista de strings | — | Um CNPJ por item, com ou sem pontuação |
| `cnpjsText` | texto | — | Cole um bloco separado por linha, vírgula, ponto e vírgula ou espaço; é somado a `cnpjs` |
| `includeSecondaryCnaes` | booleano | `true` | Atividades econômicas secundárias |
| `includeTaxRegime` | booleano | `false` | Regime tributário anual (Lucro Real / Presumido / Simples), quando publicado |
| `includePartners` | booleano | `false` | Quadro de sócios (QSA) com CPF mascarado, como a Receita Federal publica |
| `includeNotFound` | booleano | `true` | Mantém no dataset as linhas `not_found` (de graça) |
| `maxConcurrency` | inteiro | `20` | 1–50 consultas em paralelo |
| `requestTimeoutSecs` | inteiro | `20` | Timeout de cada requisição |

Exemplo de entrada:

```json
{
    "cnpjs": ["47.960.950/0001-21", "03007331000141"],
    "includeSecondaryCnaes": true,
    "includePartners": false
}
```

### Saída

Um item de dataset por CNPJ:

```json
{
    "cnpj": "47960950000121",
    "cnpj_formatted": "47.960.950/0001-21",
    "status": "ok",
    "source": "minhareceita",
    "fetched_at": "2026-11-04T18:00:00.000Z",
    "razao_social": "MAGAZINE LUIZA S/A",
    "nome_fantasia": "MAGAZINE LUIZA",
    "situacao_cadastral": "ATIVA",
    "data_inicio_atividade": "1991-05-24",
    "matriz_filial": "MATRIZ",
    "natureza_juridica": "Sociedade Anônima Aberta",
    "porte": "DEMAIS",
    "capital_social": 1300000000,
    "cnae_principal": { "codigo": "4713-0/04", "descricao": "Lojas de departamentos ou magazines, exceto lojas francas (Duty free)" },
    "endereco": {
        "municipio": "FRANCA",
        "codigo_municipio_ibge": "3516200",
        "uf": "SP",
        "cep": "14403000"
    },
    "simples_nacional": { "optante": false },
    "mei": { "optante": false }
}
```

O key-value store da execução guarda um registro `OUTPUT` com os totais: solicitados, válidos,
inválidos (listados), processados, encontrados, não encontrados, erros, taxa de sucesso e quantos
registros foram cobrados.

### Preço

**Pay per event**, quando a monetização for ligada: um evento `company-record` por CNPJ
**encontrado**, a US$ 0,001 — sem taxa de início de execução. CNPJ inválido ou não encontrado não é
cobrado. Defina um teto de gasto por execução no Apify Console; o Actor para de forma limpa ao
atingir o teto e informa onde parou. Enquanto a monetização não é ligada, a execução roda normalmente
sem cobrar nada.

### Casos de uso

- Enriquecer lista de leads ou CRM com situação cadastral, CNAE, porte e localização antes da abordagem.
- Validar CNPJ de fornecedor ou cliente em onboarding e fluxos de KYB (Know Your Business).
- Segmentar empresas por CNAE, UF, opção pelo Simples/MEI ou data de abertura.
- Alimentar agentes de IA e automações: chame o Actor pela API do Apify (endpoint
  `run-sync-get-dataset-items` devolve o resultado numa única chamada), pelo node HTTP Request do
  n8n/Make, ou via MCP (Model Context Protocol), para devolver JSON estruturado direto para o agente.

### Fonte dos dados e limites honestos

Os dados vêm dos dumps públicos de CNPJ publicados pela Receita Federal, servidos por espelhos
abertos que se atualizam a partir das liberações oficiais. Mudanças muito recentes (poucos dias)
podem ainda não estar refletidas. O Actor não acessa o site da Receita Federal, não resolve CAPTCHA
e não faz scraping — consome só APIs públicas de dados abertos.

- O quadro de sócios (QSA) é opcional (`includePartners`) e vem só com o que a própria Receita
  Federal publica: nome, qualificação, data de entrada e o CPF **já mascarado na origem**
  (`***123456**`). Este Actor nunca desmascara, cruza ou enriquece esse CPF.
- Telefone e e-mail só aparecem quando a própria empresa os informou à Receita Federal e a fonte os
  publica; quando o cadastro não tem esse dado — comum em microempresas e MEI que não preencheram o
  campo — o Actor devolve o campo vazio em vez de inventar ou buscar em outro lugar.
- Nenhum dado é enriquecido, cruzado com outra base ou inferido: o que sai é exatamente o que a
  Receita Federal publicou, reformatado.

### FAQ

**Quais formatos de CNPJ são aceitos?** Qualquer string com 14 dígitos: `47.960.950/0001-21`,
`47960950000121`, com ou sem espaços. O dígito verificador é validado antes de qualquer requisição.

**O que acontece com CNPJ inválido?** Entra na lista `invalidCnpjs` do resumo `OUTPUT` e é pulado.
Nunca é cobrado.

**Dá para rodar 100.000 CNPJs?** Sim. O progresso é salvo a cada 50 registros; se a execução for
abortada ou reiniciada, ela continua do último lote, sem cobrar de novo.

**O Actor devolve CPF?** Não. Com `includePartners` ligado, o CPF do sócio vem como a Receita
Federal já publica, mascarado (`***123456**`).

***

## CNPJ Brasil Lookup — Receita Federal company data in bulk (EN)

Turn a list of Brazilian CNPJs into clean company records from the Receita Federal public registry:
legal name, trade name, registry status, main and secondary CNAEs, full address with IBGE city code,
company phone and email (when registered), Simples Nacional and MEI flags, company size, share
capital, opening date and head-office/branch flag. Paste 1 or 100,000 CNPJs; get a dataset you can
export as JSON, CSV or Excel, or call from your own code and AI agents.

**You pay only for records that are found.** Invalid check digits and CNPJs absent from the registry
cost nothing and are reported so you can reconcile your list. No start-of-run fee.

### Why this Actor

- **Reliable**: primary open-data source (minhareceita.org, a mirror of the official Receita Federal
  dumps) with automatic retry, and a second source (BrasilAPI) as fallback. Transient failures do not
  kill your run; every CNPJ gets a status (`ok`, `not_found`, `error`).
- **Fast**: 20 parallel lookups by default, about 1,000 CNPJs per minute. Raise `maxConcurrency` up
  to 50.
- **Complete**: 40+ fields per company, including secondary CNAEs, Simples/MEI dates and optional
  yearly tax regime.
- **Resumable**: progress is persisted, so an aborted or restarted run continues where it stopped
  without charging twice.
- **Privacy by default**: only company data is returned. The partners board (QSA) is opt-in and
  comes exactly as the government publishes it, with CPFs already masked at the source. Nothing is
  enriched or unmasked.

### Input

| Field | Type | Default | Notes |
|---|---|---|---|
| `cnpjs` | array of strings | — | One CNPJ per item, with or without punctuation |
| `cnpjsText` | string | — | Paste a block separated by new lines, commas, semicolons or spaces; merged with `cnpjs` |
| `includeSecondaryCnaes` | boolean | `true` | Secondary economic activities |
| `includeTaxRegime` | boolean | `false` | Yearly tax regime (Lucro Real / Presumido / Simples) when published |
| `includePartners` | boolean | `false` | Partners board (QSA) with masked CPFs, as published by Receita Federal |
| `includeNotFound` | boolean | `true` | Keep `not_found` rows in the dataset (free) |
| `maxConcurrency` | integer | `20` | 1–50 parallel lookups |
| `requestTimeoutSecs` | integer | `20` | Per-request timeout |

Example:

```json
{
    "cnpjs": ["47.960.950/0001-21", "03007331000141"],
    "includeSecondaryCnaes": true,
    "includePartners": false
}
```

### Output

One dataset item per CNPJ:

```json
{
    "cnpj": "47960950000121",
    "cnpj_formatted": "47.960.950/0001-21",
    "status": "ok",
    "source": "minhareceita",
    "fetched_at": "2026-11-04T18:00:00.000Z",
    "razao_social": "MAGAZINE LUIZA S/A",
    "nome_fantasia": "MAGAZINE LUIZA",
    "situacao_cadastral": "ATIVA",
    "data_inicio_atividade": "1991-05-24",
    "matriz_filial": "MATRIZ",
    "natureza_juridica": "Sociedade Anônima Aberta",
    "porte": "DEMAIS",
    "capital_social": 1300000000,
    "cnae_principal": { "codigo": "4713-0/04", "descricao": "Department stores" },
    "endereco": {
        "municipio": "FRANCA",
        "codigo_municipio_ibge": "3516200",
        "uf": "SP",
        "cep": "14403000"
    },
    "simples_nacional": { "optante": false },
    "mei": { "optante": false }
}
```

The run's key-value store holds an `OUTPUT` record with totals: requested, valid, invalid (listed),
processed, found, not found, errors, success rate and how many records were charged.

### Pricing

**Pay per event**, once monetization is turned on: one `company-record` event per CNPJ **found**,
at US$ 0.001 — no start-of-run fee. Invalid and not-found CNPJs are never charged. Set a maximum
charge per run in the Apify Console to cap spending; the Actor stops cleanly when the cap is reached
and reports where it stopped. Until monetization is enabled, the Actor runs normally at no charge.

### Use cases

- Enrich a CRM or lead list with registry status, CNAE, size and location before outreach.
- Validate supplier or customer CNPJs in onboarding and KYB (Know Your Business) flows.
- Segment companies by CNAE, state, Simples/MEI option or opening date.
- Feed AI agents and automations: call the Actor through the Apify API (the
  `run-sync-get-dataset-items` endpoint returns the result in one call), through n8n/Make's HTTP
  Request node, or via MCP (Model Context Protocol) to hand structured JSON straight to an agent.

### Data source and honest limitations

Data comes from the public CNPJ dumps published by Receita Federal, served through open mirrors
that refresh from the official releases. Very recent changes (a few days old) may not be reflected
yet. The Actor does not access the Receita Federal website, does not solve CAPTCHAs and does not
scrape — it only consumes public open-data APIs.

- The partners board (QSA) is opt-in (`includePartners`) and carries only what Receita Federal
  itself publishes: name, role, entry date and the CPF **already masked at the source**
  (`***123456**`). This Actor never unmasks, cross-references or enriches that CPF.
- Phone and email only appear when the company itself reported them to Receita Federal and the
  source publishes them; when the registry has no such data — common for small businesses and MEI
  that never filled in the field — the Actor returns the field empty instead of inventing it or
  looking it up elsewhere.
- Nothing is enriched, cross-referenced with another database, or inferred: what comes out is
  exactly what Receita Federal published, reformatted.

### FAQ

**Which CNPJ formats are accepted?** Any string containing 14 digits: `47.960.950/0001-21`,
`47960950000121`, or with spaces. Check digits are validated before any request.

**What happens to invalid CNPJs?** They are listed in the `invalidCnpjs` field of the `OUTPUT`
summary and skipped. They are never charged.

**Can I run 100,000 CNPJs?** Yes. Progress is saved every 50 records; if the run is aborted or
restarted it resumes from the last batch, without charging twice.

**Do you return CPFs?** No. With `includePartners` on, partner CPFs come exactly as Receita Federal
already publishes them, masked (`***123456**`).

# Actor input Schema

## `cnpjs` (type: `array`):

One CNPJ per item, with or without punctuation (e.g. 33.000.167/0001-01 or 33000167000101). Duplicates are removed; invalid check digits are skipped and never charged.

## `cnpjsText` (type: `string`):

Alternative to the list: paste thousands of CNPJs separated by new lines, commas, semicolons or spaces. Both fields are merged.

## `includeSecondaryCnaes` (type: `boolean`):

Adds the list of secondary economic activities (code + description).

## `includeTaxRegime` (type: `boolean`):

Adds the yearly tax regime (Lucro Real / Presumido / Simples) when the public registry has it.

## `includePartners` (type: `boolean`):

Adds the partners/administrators board (QSA) exactly as published by Receita Federal: name, role, entry date and the CPF already masked by the source (\***123456**). Off by default.

## `includeNotFound` (type: `boolean`):

When on, CNPJs absent from the public registry are written with status "not_found" so you can reconcile your list. They are never charged.

## `maxConcurrency` (type: `integer`):

Parallel lookups against the primary source (1-50). 20 processes about 1,000 CNPJs per minute.

## `requestTimeoutSecs` (type: `integer`):

Per-request timeout before retrying or falling back to the secondary source.

## Actor input object example

```json
{
  "cnpjs": [
    "47.960.950/0001-21",
    "00.776.574/0001-56",
    "03.007.331/0001-41",
    "53.113.791/0001-22",
    "71.673.990/0001-77",
    "84.429.695/0001-11",
    "07.689.002/0001-89",
    "45.985.371/0001-08",
    "07.526.557/0001-00",
    "02.558.157/0001-62"
  ],
  "cnpjsText": "",
  "includeSecondaryCnaes": true,
  "includeTaxRegime": false,
  "includePartners": false,
  "includeNotFound": true,
  "maxConcurrency": 20,
  "requestTimeoutSecs": 20
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "cnpjs": [
        "47.960.950/0001-21",
        "00.776.574/0001-56",
        "03.007.331/0001-41",
        "53.113.791/0001-22",
        "71.673.990/0001-77",
        "84.429.695/0001-11",
        "07.689.002/0001-89",
        "45.985.371/0001-08",
        "07.526.557/0001-00",
        "02.558.157/0001-62"
    ],
    "cnpjsText": ""
};

// Run the Actor and wait for it to finish
const run = await client.actor("talesferraz/cnpj-brasil-lookup").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "cnpjs": [
        "47.960.950/0001-21",
        "00.776.574/0001-56",
        "03.007.331/0001-41",
        "53.113.791/0001-22",
        "71.673.990/0001-77",
        "84.429.695/0001-11",
        "07.689.002/0001-89",
        "45.985.371/0001-08",
        "07.526.557/0001-00",
        "02.558.157/0001-62",
    ],
    "cnpjsText": "",
}

# Run the Actor and wait for it to finish
run = client.actor("talesferraz/cnpj-brasil-lookup").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "cnpjs": [
    "47.960.950/0001-21",
    "00.776.574/0001-56",
    "03.007.331/0001-41",
    "53.113.791/0001-22",
    "71.673.990/0001-77",
    "84.429.695/0001-11",
    "07.689.002/0001-89",
    "45.985.371/0001-08",
    "07.526.557/0001-00",
    "02.558.157/0001-62"
  ],
  "cnpjsText": ""
}' |
apify call talesferraz/cnpj-brasil-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,talesferraz/cnpj-brasil-lookup"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/3jDqkxnetwnt2WaXP/builds/dhnoJKGlZ94vWwbyE/openapi.json