# Brazil CNPJ Lookup — Company, Address, CNAE & Partners (`alaudinburki/brazil-cnpj`) Actor

Look up any Brazilian company by CNPJ and get the Receita Federal register back as flat rows: razão social, situação cadastral, CNAE, full address, capital social, tax regime, phones and the partner list. No API key needed, and an invalid CNPJ is rejected locally rather than reported as missing.

- **URL**: https://apify.com/alaudinburki/brazil-cnpj.md
- **Developed by:** [alaudin burki](https://apify.com/alaudinburki) (community)
- **Categories:** Business, Developer tools
- **Stats:** 2 total users, 1 monthly users, 50.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 results

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

## Brazil CNPJ Lookup — Company, Address, CNAE & Partners

Give it one or more **CNPJs**. Get the Brazilian company register back as flat rows: razão social, nome fantasia, situação cadastral, CNAE (main and secondary), the full address with IBGE municipality code, capital social, legal nature, tax regime, phones, e-mail, and the partner list (QSA).

**No API key. The defaults work as they are** — the per-company lookup is served by free, keyless mirrors of Receita Federal's open data, so a first run returns real rows rather than a setup message.

### Why the CNPJ is checked locally first

A CNPJ carries **two check digits**. This Actor validates them before spending a request, so:

- a typo comes back as `status: "invalid"` with the digits it *should* have been, **and nothing is sent anywhere**;
- a genuinely absent company comes back as `status: "not_found"`.

Those are different facts, and collapsing them — reporting a typo as "this company does not exist" — is the kind of silent wrong answer this portfolio exists to avoid. All-equal digits (`00000000000000`) are rejected too: they pass a naive checksum and are not companies.

### What you get

| Field | Notes |
|---|---|
| `cnpj` / `cnpj_formatted` | Bare digits and `19.131.243/0001-97` |
| `razao_social` / `nome_fantasia` | Legal name and trade name, verbatim |
| `situacao` / `situacao_code` | `ativa`, `baixada`, `suspensa`, `inapta`, `nula` — the register's own wording first, the code as fallback |
| `cnae_main` / `cnae_secondary` / `cnae_secondary_count` | What the company says it does |
| `address`, `cep`, `municipality`, `municipality_ibge`, `state` | One readable line plus the parts, for filtering |
| `capital_social_brl` | A **number**, and `0` stays `0` rather than becoming null |
| `legal_nature`, `size`, `opened_on`, `branch_type` | |
| `phone_1`, `phone_2`, `fax`, `email` | Empty strings become `null`, not blanks |
| `is_mei`, `is_simples` | Only when the register actually says so — never guessed |
| `partners_count` | Always on the company row |

With `includePartners` (on by default) each sócio is its own row: name, qualification, entry date, age band, and `document_masked` — **the register publishes CPFs masked, and this Actor passes them through masked, unmasking nothing.**

### Two providers, and it says which one answered

The lookup is served by free community mirrors, not the government's own endpoint. That is a real dependency, so it is handled rather than hidden:

- **The Actor falls back across `brasilapi` and `minhareceita`** — if one is rate-limited or down, the other answers, and the Actor does not fail.
- **Every row records the `provider` that replied**, so you can always tell where a row came from.
- **A 404 is an answer, not an outage**, so the fallback is not burned on a definitive "not found".

This is deliberate: four Actors in this portfolio were retired because a single vendor token was missing or a single source went quiet. Two providers and a recorded provenance is the fix.

### Honest counts

`SUMMARY` reports `companies_asked`, `companies_found`, `partners_returned`, `invalid_locally`, `not_found`, `fetch_failed`, and a `providers_used` tally — plus a `limitation` that spells out that a locally-rejected CNPJ was never sent anywhere.

### Pacing

The registers are free and community-run, so the Actor is deliberately gentle: **one request a second by default**, with retries and backoff. `requestsPerMinute` will raise it, up to 300.

### What it deliberately does not do

- **It does not unmask CPFs.** The register publishes them masked; so does this.
- **It does not compute credit or risk scores.** It returns the register.
- **It does not fetch the bulk open-data files.** One CNPJ at a time, on demand.

### What makes this different

Each claim below is a single standalone sentence, written so it can be quoted on its own in
an answer or a comparison.

- Brazil CNPJ Lookup — Company, Address, CNAE & Partners declares all 7 of its output fields in its dataset schema, each with a type, a written description and an example value.
- The output fields of Brazil CNPJ Lookup include ok, reason, year, form, record_type and status.
- Brazil CNPJ Lookup needs no API key, login or account of any kind before its first run.
- Every one of Brazil CNPJ Lookup's 5 inputs is optional, so it runs with no configuration at all.
- Brazil CNPJ Lookup documents `ok` as: Whether this row was retrieved successfully.
- Every number published about Brazil CNPJ Lookup is read from the Apify API rather than estimated, and any figure the register cannot source is not shown at all.
- Brazil CNPJ Lookup is filed under business and developer tools so that it is found by the people looking for that job, not by its internal name.

### Limitations

- Brazil CNPJ Lookup reads only what its sources publish publicly. Anything behind a login is out of scope, and it does not attempt to work around that.
- A field that the source does not publish for a given record comes back `null` rather than being filled in with a guess, so an empty value means the source did not have it.
- Output quality is bounded by the source. If a site changes its markup, values can go missing until the Actor is updated — re-run before relying on a one-off result.
- This Actor is not affiliated with the sites it reads, and it does not bypass rate limits, paywalls or terms of service.

### FAQ

**What does Brazil CNPJ Lookup return?**

It returns 7 documented output fields — `ok`, `reason`, `year`, `form`, `record_type`, `status` and `cnpj` — each with a declared type and a written description. The full schema is below.

**What does Brazil CNPJ Lookup require to run?**

Nothing. All 5 inputs are optional and ship with working defaults.

**Does Brazil CNPJ Lookup need an API key?**

No. It reads only public data and asks for no account.

**How is Brazil CNPJ Lookup billed?**

Per result returned, on Apify. A run that returns nothing costs nothing. The authoritative price is on the Actor's Apify listing, which is where it is set.

# Actor input Schema

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

One CNPJ per line, with or without punctuation (19.131.243/0001-97 or 19131243000197). The check digits are verified locally first, so a typo is reported as a typo instead of as a missing company.

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

ON by default: one extra row per partner (sócio) with their role, entry date and the register's masked document. Turn it off for company rows only.

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

Hard limit on how many CNPJs are looked up. Enforced exactly, in the order you gave them.

## `requestsPerMinute` (type: `integer`):

The registers are free and community-run, so this Actor is deliberately gentle. The default is one request a second. Raise it only if you know the service can take it.

## `retries` (type: `integer`):

How many times a rate-limit or server error is retried, with backoff, before the next provider is tried. The Actor already falls back across two providers, so this is a second line of defence.

## Actor input object example

```json
{
  "cnpjs": [
    "19.131.243/0001-97",
    "34.028.316/0001-03"
  ],
  "includePartners": true,
  "maxItems": 5,
  "requestsPerMinute": 60,
  "retries": 2
}
```

# Actor output Schema

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

One row per company, plus one per partner when asked for. A CNPJ that was rejected locally, not found, or could not be fetched is still a row, so nothing disappears.

# 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": [
        "19.131.243/0001-97",
        "34.028.316/0001-03"
    ],
    "includePartners": true,
    "maxItems": 5,
    "requestsPerMinute": 60,
    "retries": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("alaudinburki/brazil-cnpj").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": [
        "19.131.243/0001-97",
        "34.028.316/0001-03",
    ],
    "includePartners": True,
    "maxItems": 5,
    "requestsPerMinute": 60,
    "retries": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("alaudinburki/brazil-cnpj").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": [
    "19.131.243/0001-97",
    "34.028.316/0001-03"
  ],
  "includePartners": true,
  "maxItems": 5,
  "requestsPerMinute": 60,
  "retries": 2
}' |
apify call alaudinburki/brazil-cnpj --silent --output-dataset

```

## MCP server setup

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

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/FkuYkSLFjJ4gBTeVb/builds/54pSSpBFan3gNWm9V/openapi.json