# Brazil CNPJ Receita Federal Scraper (`memo23/brazil-cnpj-receita-federal-scraper`) Actor

Turn Receita Federal's registry into lead lists: every Brazilian company by state, CNAE industry, city, or legal form — 55M+ CNPJs with partners (QSA), tax-regime flags, capital, and phone where the registry has it. Active-only filtering, multi-state sweeps, single-CNPJ KYC lookups

- **URL**: https://apify.com/memo23/brazil-cnpj-receita-federal-scraper.md
- **Developed by:** [Muhamed Didovic](https://apify.com/memo23) (community)
- **Categories:** Lead generation, AI, Agents
- **Stats:** 1 total users, 1 monthly users, 90.9% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 company records

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Brazil CNPJ Receita Federal Scraper

Get the full official registry record for any Brazilian company — or discover thousands of companies at once by state, industry, city, legal form, or partner. Built on Receita Federal open data covering all 55M+ registered CNPJs, returned as clean, structured JSON.

**Find the companies, don't just verify them.** Most CNPJ tools take a CNPJ you already know and return one record. This scraper also works the other way round: give it a CNAE industry code and a state, and it walks the whole registry to hand you every matching company — partners, tax flags, address, and phone included. (Contact coverage is whatever Receita Federal publishes — see [Data coverage](#-data-coverage-measured) for the measured numbers before you plan a campaign around it.)

![How Brazil CNPJ Receita Federal Scraper works](https://raw.githubusercontent.com/muhamed-didovic/muhamed-didovic.github.io/main/assets/how-it-works-brazil-cnpj.png)

#### ✨ Why use this scraper?

- **Bulk discovery, not just enrichment** — sweep the registry by state (UF), CNAE code, municipality, legal form, or partner CPF; or look up specific CNPJs directly.
- **Multi-value filters** — `"uf": "SP,RJ,MG"` sweeps three states in one run. Every filter accepts comma-separated lists; competitors make you run one job per value.
- **Structured output that stays machine-readable** — the partner list (QSA) and secondary CNAEs come back as JSON objects, not flattened display strings.
- **Active-only filtering** — set `situacaoCadastral: "ATIVA"` and dead CNPJs are dropped before they reach your dataset (and are never charged).
- **Ownership graph on demand** — direct lookups can attach the company's partner network from the open CNPJ graph API.
- **CPFs masked by default** — Receita Federal bakes a sole proprietor's full 11-digit CPF into the legal name (`JOAO SILVA 02898774073`). This Actor masks it to `JOAO SILVA ***.987.740-**` and flags the row with `cpf_masked: true`, so you don't inherit raw personal data you then have to redact.
- **Honest coverage, measured not promised** — phone and address are sparse in the source registry; the real hit rates are published below instead of implied away.
- **No proxy, no captcha, no browser** — the data sits behind a plain JSON API. Cheap, fast, and hard to break.
- **Cursor pagination** — walks the upstream cursor directly, so results don't silently skip past the 10k mark the way offset-based scrapers do.

#### 🎯 Use cases

| Who | What they do with it |
|---|---|
| B2B prospecting teams | Pull every company in a CNAE + state combo into the CRM instead of buying lead lists |
| Fintechs & KYC providers | Verify customer CNPJs and capture the partner network (QSA) for AML screening |
| Tax consultancies | Filter by Simples Nacional / MEI opt-ins and tax-regime history to segment prospects |
| Trade-credit insurers | Pre-fill underwriting with status, capital, opening date, and partners — no per-call enrichment fees |
| Researchers & journalists | Map ownership chains via masked partner CPFs and the ownership graph |
| Marketplaces & platforms | Validate seller CNPJs at onboarding and monitor registration status |

#### 📥 Supported inputs

**Direct lookup** — one or more CNPJs (formatting is ignored):

```json
{ "cnpj": ["00.000.000/0001-91", "33683111000280"] }
```

**Bulk search** — at least one filter; all accept comma-separated multi-values:

```json
{ "uf": "SP", "cnae": "6209100", "maxItems": 5000 }
```

| Filter | Meaning | Example |
|---|---|---|
| `uf` | Two-letter state code(s) | `"SP"` or `"SP,RJ,MG"` |
| `cnae` | CNAE industry code(s), matches primary and secondary activities | `"6209100"` (IT support) |
| `municipio` | IBGE/SIAFI municipal code(s) — digits, not city names | `"3550308"` (São Paulo) |
| `naturezaJuridica` | Legal-form code(s) | `"2135"` (sole proprietor) |
| `partnerCpf` | Partner CPF (masked `***123456**` format) or CNPJ in the QSA | `"***456789**"` |

**Unsupported inputs:** city names in `municipio` (use the IBGE code), unmasked CPFs (Receita Federal only publishes masked ones), free-text company-name search, and filter-less full-registry sweeps (they time out upstream and are rejected up front).

#### 🔄 How it works

1. **Pick a mode.** Provide CNPJs for direct lookups, or set at least one filter for a bulk crawl.
2. The scraper queries the open Receita Federal CNPJ API ([minhareceita.org](https://minhareceita.org)), which mirrors the government's monthly bulk dumps.
3. Bulk runs walk the cursor-paginated search, up to 1,000 records per call, until `maxItems` is reached or the results run out.
4. Records are deduplicated by CNPJ, optionally filtered to a registration status (e.g. only `ATIVA`), CPF-masked (see below), and mapped into the structured row shape.
5. Results stream into the Apify dataset as they arrive — stop the run any time and keep what's already saved. Export as JSON, CSV, or Excel.

#### ⚙️ Input parameters

| Field | Type | Default | Description |
|---|---|---|---|
| `cnpj` | array | — | CNPJs for direct lookup (dots/slashes/dashes ignored). Overrides all search filters. |
| `uf` | string | — | State code(s), comma-separated for multiple. |
| `cnae` | string | — | CNAE code(s), comma-separated. Matches primary and secondary activities. |
| `municipio` | string | — | IBGE or SIAFI municipal code(s), digits only, comma-separated. |
| `naturezaJuridica` | string | — | Legal-form code(s), comma-separated. |
| `partnerCpf` | string | — | Partner CPF/CNPJ in the QSA. CPFs use the masked `***123456**` format. |
| `situacaoCadastral` | select | all | Keep only one registration status: `ATIVA`, `BAIXADA`, `INAPTA`, `SUSPENSA`, or `NULA`. |
| `includeGraph` | boolean | `false` | Direct lookups only: attach the ownership graph (`grafo` field). One extra call per CNPJ. |
| `unmaskSoleProprietorCpf` | boolean | `false` | **Off by default.** Returns the sole proprietor's full 11-digit CPF inside `razao_social` instead of the masked form. Only turn this on with a lawful basis under the LGPD. |
| `maxItems` | integer | `100` | Hard cap on records saved. Keep low on first runs. |
| `pageSize` | integer | `1000` | Records per upstream API page (1–1000). The default is the upstream maximum and the fastest option. |
| `maxConcurrency` | integer | `5` | Parallel requests for multi-CNPJ direct lookups. |

**Every IT-support company in São Paulo state:**

```json
{ "uf": "SP", "cnae": "6209100", "situacaoCadastral": "ATIVA", "maxItems": 5000 }
```

**KYC lookup with ownership graph:**

```json
{ "cnpj": ["00.000.000/0001-91"], "includeGraph": true }
```

**Sole proprietors (MEI-style) in Brasília:**

```json
{ "municipio": "5300108", "naturezaJuridica": "2135", "maxItems": 1000 }
```

#### 📊 Output overview

One dataset row per company. Field names follow the official Receita Federal data dictionary (Portuguese), so the output lines up with every other Brazilian registry tool your team uses. Nested data stays structured: `qsa` (partner board) is an array of objects, `cnaes_secundarios` is an array of `{codigo, descricao}` pairs, and `regime_tributario` carries the per-year tax-regime history.

**Two things worth knowing before you build on the output:**

- `razao_social` for a sole proprietor (*Empresário Individual*, legal-form code `2135`) is the person's name followed by their CPF. The Actor masks it — `JOAO SILVA 02898774073` becomes `JOAO SILVA ***.987.740-**` — and sets `cpf_masked: true` on that row. Set `unmaskSoleProprietorCpf: true` if you need the raw value and have a lawful basis for it.
- `email` is in the row shape for schema stability, but it is **empty in practice**: Receita Federal's public bulk dump does not publish company email addresses. Across three separate 1,000-record samples of the live source (2026-07 dump), **0 records carried an email**. Do not plan an email campaign around this field.

#### 📦 Output sample

Trimmed real row from a direct lookup of Banco do Brasil (`00000000000191`):

```json
{
  "cnpj": "00000000000191",
  "razao_social": "BANCO DO BRASIL SA",
  "cpf_masked": false,
  "nome_fantasia": "DIRECAO GERAL",
  "matriz_filial": "MATRIZ",
  "situacao_cadastral": "ATIVA",
  "situacao_cadastral_motivo": "SEM MOTIVO",
  "data_situacao_cadastral": "2005-11-03",
  "data_abertura": "1966-08-01",
  "cnae_principal_codigo": "6422100",
  "cnae_principal_descricao": "Bancos múltiplos, com carteira comercial",
  "cnaes_secundarios": [
    { "codigo": "6499999", "descricao": "Outras atividades de serviços financeiros não especificadas anteriormente" }
  ],
  "natureza_juridica_codigo": "2038",
  "natureza_juridica": "Sociedade de Economia Mista",
  "porte": "DEMAIS",
  "capital_social": 120000000000,
  "logradouro": "QUADRA SAUN QUADRA 5 BLOCO B TORRE I, II, III",
  "numero": "SN",
  "bairro": "ASA NORTE",
  "municipio": "BRASILIA",
  "codigo_municipio_ibge": "5300108",
  "uf": "DF",
  "cep": "70040912",
  "telefone1": "6134939002",
  "email": null,
  "simples_nacional": false,
  "mei": false,
  "regime_tributario": [
    { "ano": 2021, "forma_de_tributacao": "LUCRO REAL" }
  ],
  "orgao_publico": false,
  "qsa": [
    {
      "nome": "ALAN CARLOS GUEDES DE OLIVEIRA",
      "qualificacao": "Diretor",
      "cnpj_cpf": "***550179**",
      "data_entrada": "2023-05-17",
      "faixa_etaria": "Entre 41 a 50 anos"
    }
  ],
  "qsa_count": 41,
  "data_atualizacao_base": "2026-07",
  "source_url": "https://minhareceita.org/00000000000191"
}
```

A sole-proprietor row from a bulk sweep, showing the CPF masking and the typical sparse contact data:

```json
{
  "cnpj": "41985107000113",
  "razao_social": "JOAO FERNANDES DE LIMA ***.381.448-**",
  "cpf_masked": true,
  "nome_fantasia": null,
  "natureza_juridica_codigo": "2135",
  "natureza_juridica": "Empresário (Individual)",
  "porte": "MICRO EMPRESA",
  "telefone1": null,
  "email": null,
  "qsa": [],
  "qsa_count": 0
}
```

#### 📈 Data coverage (measured)

The registry is a legal filing database, not a contact database. These are real counts from the live source (2026-07 extraction), 1,000 records per sample, so you can size a campaign before you pay for one:

| Sample | `email` | `telefone1` | `logradouro` |
|---|---|---|---|
| `uf: "SP"` — no other filter | **0 / 1000** | 369 / 1000 (37%) | 409 / 1000 (41%) |
| `uf: "MG"` — no other filter | **0 / 1000** | 302 / 1000 (30%) | 330 / 1000 (33%) |
| `uf: "SP", cnae: "6201501"` (software houses) | **0 / 1000** | 854 / 1000 (85%) | 862 / 1000 (86%) |

What this means in practice:

- **Email is dead upstream, everywhere.** Receita Federal's public dump does not carry it. The field exists in the output but is effectively always `null`.
- **An unfiltered state sweep is contact-poor.** Roughly a third of those rows are dormant sole proprietors and shell registrations that never filed a phone or a street address. In the `uf: "SP"` sample, 240 of 1,000 records were sole proprietors.
- **A CNAE-filtered sweep is contact-rich.** Filtering to a real trading industry more than doubles the hit rate (85% phone). If you want leads rather than a census, always pair `uf` with `cnae`, and add `situacaoCadastral: "ATIVA"`.
- Every field is passed through exactly as the registry publishes it — the Actor never invents, guesses, or enriches a missing value.

#### 🗂 Key output fields

- **Identity** — `cnpj`, `razao_social` (legal name, with any embedded CPF masked), `cpf_masked` (was a CPF masked in this row), `nome_fantasia` (trade name), `matriz_filial` (head office vs branch)
- **Status** — `situacao_cadastral` (+ reason and date), `data_abertura` (opening date), `situacao_especial`
- **Industry** — `cnae_principal_codigo` / `cnae_principal_descricao`, `cnaes_secundarios[]` (structured)
- **Legal & size** — `natureza_juridica` (+ code), `porte` (size class), `capital_social` (declared capital, BRL), `orgao_publico`
- **Address** — `logradouro`, `numero`, `complemento`, `bairro`, `municipio`, `codigo_municipio_ibge`, `uf`, `cep`
- **Contact** — `telefone1`, `telefone2`, `fax` (sparse — see the coverage table above), and `email` (present in the schema, but the registry never publishes it, so expect `null`)
- **Tax flags** — `simples_nacional`, `mei` (each with opt-in/opt-out dates), `regime_tributario[]` per-year history
- **Partners** — `qsa[]` (name, role, masked CPF/CNPJ, entry date, age bracket), `qsa_count`, optional `grafo[]` ownership graph
- **Provenance** — `data_atualizacao_base` (upstream extraction month), `source_url`

#### ❓ FAQ

**How current is the data?**
Receita Federal publishes bulk dumps monthly and the upstream mirror reloads from them, so records are typically 0–45 days behind the official source. Every row carries `data_atualizacao_base` so you know exactly which extraction month you're looking at.

**Do I need proxies?**
No. The data is served from a public JSON API behind a CDN — no captcha, no anti-bot, no browser. That's also why runs are fast and cheap.

**Can I search by company name?**
No — the registry API doesn't support free-text name search. Discover companies via CNAE, state, municipality, legal form, or partner CPF, then filter the output.

**Are the partner CPFs legal to use?**
Receita Federal itself publishes QSA partner CPFs pre-masked (`***123456**`), and the scraper passes them through as-is.

**So does any complete CPF reach my dataset?**
Not with the default settings. There is one place where the source leaks a full CPF: for a sole proprietor (*Empresário Individual*, legal-form code `2135`) the registry stores the legal name as `NAME 02898774073`, with the person's complete 11-digit CPF appended. That is roughly a quarter of an unfiltered state sweep.

Receita does not punctuate these consistently — the same field turns up `02898774073`, `490.722.426-53`, `082725916-69`, and `CPF: 013.636.826-36`. The Actor masks **all** of those shapes in the Receita convention — `NAME ***.987.740-**` — and sets `cpf_masked: true` on the row. Verified on 4,000 live records across MG, SP, RJ and BA: 1,227 name fields carried a CPF and every one is masked, with no company name mis-masked. If you genuinely need the raw number and have a lawful basis for processing it under the LGPD, set `unmaskSoleProprietorCpf: true`; that responsibility is then yours.

**Does the output include company email addresses?**
No. The `email` field exists in the row shape, but Receita Federal's public bulk dump does not publish it — three separate 1,000-record samples of the live source returned 0 emails. Treat it as permanently `null` and see the [coverage table](#-data-coverage-measured) for what phone and address coverage really look like.

**My run finished with 0 records — did it break?**
No, that's a valid answer and the run correctly reports `SUCCEEDED`. The log ends with a `[RESULT]` line and the run's status message naming the cause: the CNPJ isn't in the registry (upstream 404), its check digits don't validate, the filters matched nothing, or everything was dropped by `situacaoCadastral`. Note the run-start fee still applies to an empty run.

**Why does my partner-CPF search time out?**
Partner-only searches are heavy upstream. Combine `partnerCpf` with a `uf` filter to narrow the scan — that resolves it in almost every case.

**What does `orgao_publico` mean?**
It's `true` when the company's legal-form code belongs to the public-administration group (codes 1000–1999) — useful for excluding government bodies from lead lists.

**How do I keep only active companies?**
Set `situacaoCadastral: "ATIVA"`. Filtered-out records don't count toward `maxItems` and are never charged.

**How do I limit cost?**
Set `maxItems`. The run stops saving as soon as the cap is reached; you pay per dataset record.

#### 💬 Support

- For issues or feature requests, please use the **Issues** tab on the actor's Apify Console page.
- Author's website: <https://muhamed-didovic.github.io/>
- Email: <muhamed.didovic@gmail.com>

#### 🛠 Additional services

- Custom output shape, additional fields, or one-off datasets: <muhamed.didovic@gmail.com>
- Need other Brazilian data sources (real estate, marketplaces, reviews) wired in? Drop an email.
- For API access (no Apify fee, just a usage fee for the API): <muhamed.didovic@gmail.com>

#### 🔎 Explore more scrapers

If this Brazil CNPJ Scraper was useful, see other scrapers and actors at [memo23's Apify profile](https://apify.com/memo23) — covering Brazilian real estate (VivaReal, ZAP Imóveis), job boards, review platforms, and more.

### 🤖 For AI Agents & LLM Apps

Compact reference for AI agents calling this actor via the [Apify MCP server](https://mcp.apify.com) or the Apify API (actor: `memo23/brazil-cnpj-receita-federal-scraper`).

**Purpose:** look up Brazilian company registry records by CNPJ, or bulk-discover companies from Receita Federal open data by state, CNAE industry code, municipality, legal form, or partner CPF — with multi-value filters and structured (non-flattened) partner/CNAE data.

**Minimal input:**

```json
{ "uf": "DF", "cnae": "6209100", "maxItems": 25 }
```

**Output:** one dataset row per company — `cnpj`, `razao_social`, `cpf_masked`, `nome_fantasia`, `matriz_filial`, `situacao_cadastral`, `data_abertura`, `cnae_principal_codigo`, `cnae_principal_descricao`, `cnaes_secundarios [{codigo, descricao}]`, `natureza_juridica`, `porte`, `capital_social`, `logradouro`, `numero`, `bairro`, `municipio`, `codigo_municipio_ibge`, `uf`, `cep`, `telefone1`, `email`, `simples_nacional`, `mei`, `regime_tributario [{ano, forma_de_tributacao}]`, `orgao_publico`, `qsa [{nome, qualificacao, cnpj_cpf, data_entrada}]`, `qsa_count`, `grafo` (opt-in), `data_atualizacao_base`, `source_url`.

**Behaviors an agent should know:**

- Always set `maxItems` — the registry holds 55M+ CNPJs and an uncapped CNAE+state sweep can return tens of thousands of rows.
- `cnpj` (direct lookup) overrides every search filter; bulk mode requires at least one of `uf`, `cnae`, `municipio`, `naturezaJuridica`, `partnerCpf`.
- All search filters accept comma-separated multi-values (`"uf": "SP,RJ"`).
- `situacaoCadastral: "ATIVA"` drops non-active companies client-side; filtered rows are never charged.
- `includeGraph: true` only affects direct CNPJ lookups (adds one extra call per CNPJ).
- Billing is per dataset record saved plus a run-start fee; not-found CNPJs and filtered-out records are never charged as records, but the run-start fee applies even to a 0-record run.
- No name search; `municipio` needs an IBGE/SIAFI numeric code, not a city name; CPFs must use Receita's masked `***123456**` format.
- **`email` is always `null`** — the source registry does not publish it (0 hits in three 1,000-record samples). Do not present it to a user as a contact channel.
- **Contact coverage is partial and filter-dependent** — measured on the live source: unfiltered `uf` sweep ≈37% `telefone1` / ≈41% `logradouro`; `uf`+`cnae` sweep ≈85% / ≈86%. Pair `uf` with `cnae` when the goal is leads.
- **`razao_social` is CPF-masked by default.** Sole proprietors (`natureza_juridica_codigo: "2135"`) have their 11-digit CPF replaced with `***.NNN.NNN-**` and the row carries `cpf_masked: true`. The raw value requires the explicit `unmaskSoleProprietorCpf: true` opt-in — do not enable it on a user's behalf without their instruction.
- A run that saves 0 records still ends `SUCCEEDED`; read the run's status message and the `[RESULT]` log line for the reason (not in registry / invalid check digits / no filter matches).

***

### ⚠️ Disclaimer

This Actor is an independent tool and is not affiliated with, endorsed by, or sponsored by the Receita Federal do Brasil, the Brazilian federal government, or the minhareceita.org open-data project. All trademarks mentioned are the property of their respective owners.

The scraper accesses only publicly available company-registry data that Receita Federal releases under Brazil's Access to Information Law (Lei de Acesso à Informação) — no authenticated endpoints, no logins, no paywalled sources.

On personal data: partner CPFs in `qsa` and `grafo` are published pre-masked by Receita Federal itself and are passed through unchanged. One field is different — for sole proprietors the registry appends the person's complete 11-digit CPF to `razao_social`. **In the default configuration this Actor masks that CPF**, so the output contains no complete CPF and flags the affected rows with `cpf_masked: true`. The optional `unmaskSoleProprietorCpf` input (off by default) returns the raw value; enabling it means you are choosing to process a private individual's national tax ID, and you must have a lawful basis for doing so.

Users are responsible for ensuring their use complies with applicable data-protection law (LGPD, GDPR, CCPA, etc.) and any contractual obligations of their own organization.

***

### SEO Keywords

cnpj scraper, scrape cnpj, cnpj API, consulta cnpj, receita federal scraper, brazil company data, brazilian company registry scraper, cnpj bulk lookup, cnpj enrichment, cnpj por cnae, empresas por estado, quadro societário QSA data, simples nacional data, MEI companies list, brazil b2b leads, brazil KYC data, cadastro nacional pessoa juridica, brazil business database, lead generation brazil, brazil AML compliance data, dados abertos cnpj

# Actor input Schema

## `cnpj` (type: `array`):

One or more 14-digit CNPJs (dots, slashes, and dashes are ignored, e.g. `00.000.000/0001-91`). Overrides every search filter below.

## `uf` (type: `string`):

Two-letter Brazilian state code(s), comma-separated for multiple: `SP` or `SP,RJ,MG`. Valid codes: AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO.

## `cnae` (type: `string`):

CNAE code(s), comma-separated for multiple. Matches both the primary and secondary activities of a company. Example: `6209100` (IT support services) or `6209100,6201501`.

## `municipio` (type: `string`):

IBGE or SIAFI municipal code(s), digits only, comma-separated for multiple. NOT a city name — `TATUÍ` will be rejected. Find codes at https://www.ibge.gov.br/explica/codigos-dos-municipios.html — e.g. `5300108` (Brasília), `3550308` (São Paulo).

## `naturezaJuridica` (type: `string`):

Legal-form code(s), comma-separated for multiple. Example: `2135` (Empresário Individual / sole proprietor), `2062` (Sociedade Empresária Limitada / LTDA).

## `partnerCpf` (type: `string`):

CPF or CNPJ of a person/entity in the company's partner list (QSA), comma-separated for multiple. For CPFs use the masked Receita format `***123456**` (asterisks for the first three and last two digits, no dots or dashes) — that is how Receita Federal publishes them. Tip: partner-only searches can time out upstream; combining with a `uf` filter helps.

## `situacaoCadastral` (type: `string`):

Only save companies with this registration status — e.g. `ATIVA` to skip dead CNPJs in lead-gen runs. Filtered-out records are never charged. Applied client-side; `ALL` keeps everything. (An empty string is still accepted as a synonym for `ALL`, so older saved inputs keep working.)

## `includeGraph` (type: `boolean`):

For direct CNPJ lookups, adds a `grafo` field with the company's ownership-graph entries (people and entities connected via partner boards) from the open grafo.minhareceita.org API. One extra HTTP call per CNPJ; ignored in bulk-search mode.

## `unmaskSoleProprietorCpf` (type: `boolean`):

OFF by default. Receita Federal stores a sole proprietor's legal name as `NAME 02898774073` — the person's full 11-digit CPF. By default this Actor masks it to `NAME ***.987.740-**` and sets `cpf_masked: true`. Turn this ON only if you have a lawful basis under the LGPD to process the complete CPF — the raw number is personal data of a private individual, and you become responsible for handling it.

## `maxItems` (type: `integer`):

Hard cap on the number of company records saved across the whole run. The registry holds 55M+ CNPJs — keep this low on first runs to validate the output.

## `pageSize` (type: `integer`):

Records requested per upstream API page (1–1000). The default of 1000 is the upstream maximum and the fastest option; lower it only if you hit upstream timeouts on very heavy filter combinations.

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

Parallel requests when looking up multiple CNPJs directly. Kept modest by default — minhareceita.org is a donation-funded community mirror.

## Actor input object example

```json
{
  "uf": "SP",
  "situacaoCadastral": "ALL",
  "includeGraph": false,
  "unmaskSoleProprietorCpf": false,
  "maxItems": 100,
  "pageSize": 1000,
  "maxConcurrency": 5
}
```

# 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 = {
    "uf": "SP"
};

// Run the Actor and wait for it to finish
const run = await client.actor("memo23/brazil-cnpj-receita-federal-scraper").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 = { "uf": "SP" }

# Run the Actor and wait for it to finish
run = client.actor("memo23/brazil-cnpj-receita-federal-scraper").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 '{
  "uf": "SP"
}' |
apify call memo23/brazil-cnpj-receita-federal-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,memo23/brazil-cnpj-receita-federal-scraper"
        }
    }
}

```

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/3QaMNALtXfM7Odnzg/builds/2ICZMjLUWVRKYHfSL/openapi.json