# CNPJ Lookup – Brazil Company Data (Consulta CNPJ em Lote) (`cairolabs/brazil-cnpj-enrichment`) Actor

Bulk CNPJ lookup for Brazilian company data: legal name (razão social), status (situação cadastral), CNAE, address, email, phones, QSA partners (sócios), Simples/MEI, company age. Receita Federal open data, 2 sources with failover. Use as a CNPJ API. Pay only per company found.

- **URL**: https://apify.com/cairolabs/brazil-cnpj-enrichment.md
- **Developed by:** [Cairo Labs](https://apify.com/cairolabs) (community)
- **Categories:** Lead generation, Business, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$6.00 / 1,000 company enricheds

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 lookup** for Brazilian companies, in bulk: paste a list (or a spreadsheet column) of CNPJs and get clean **Brazil company data** — legal name (razão social), trade name (nome fantasia), registration status (situação cadastral), CNAE activities, full address, email, phones, **QSA partners (sócios)**, Simples Nacional / MEI, share capital, company size and company age.

Data comes from the **Receita Federal open dataset (Dados Abertos CNPJ)** via two public mirrors (BrasilAPI → minhareceita.org) with automatic failover. No login, no proxy, no scraping of the Receita website. Use it as a no-code tool or as a **CNPJ API** through the Apify API.

### What does this Brazilian company search do?

- 💸 **Pay only for companies found** – invalid check digits and not-found CNPJs are free.
- ✅ **Check-digit validation** before any request; duplicates are looked up once.
- 🔁 **Failover + retries** with exponential backoff on 429/5xx; configurable concurrency and delay (rate limiting).
- 📋 **Spreadsheet friendly** – flat fields + one row per input (errors included), export to CSV/Excel/JSON.
- 🧮 **Derived fields**: `isActive`, `companyAgeYears`, `partnersCount`, `isHeadquarters`.

**Use cases:** B2B lead enrichment, KYC/KYB & supplier onboarding, CRM cleanup, credit/compliance checks, market mapping by CNAE.

### How do I look up CNPJs in bulk? (step by step)

1. Paste your CNPJs in `cnpjs` (with or without punctuation) or paste a CSV/text column in `csvText`.
2. Click **Start** to run the Actor.
3. Download the dataset as CSV, Excel or JSON, or read it through the Apify API.

### Input example (JSON)

```json
{ "cnpjs": ["33.000.167/0001-01", "18236120000158"], "maxConcurrency": 3, "delayMs": 400 }
```

| Field | Default | Description |
|---|---|---|
| `cnpjs` | – | List of CNPJs (any punctuation) |
| `csvText` | – | Paste any text/CSV column with CNPJs |
| `maxItems` | 10000 | Max CNPJs per run (cost cap) |
| `maxConcurrency` | 3 | Parallel lookups (1–10) |
| `delayMs` | 400 | Pause per worker between lookups |
| `maxRetries` | 2 | Retries per source (0–5) |
| `skipInvalid` | false | Omit invalid CNPJs from output |
| `includeRaw` | false | Add full source record under `raw` |

### Output example (real sample)

```json
{
  "cnpjFormatted": "18.236.120/0001-58", "found": true, "source": "brasilapi",
  "legalName": "NU PAGAMENTOS S.A. - INSTITUICAO DE PAGAMENTO", "status": "ATIVA", "isActive": true,
  "openingDate": "2013-05-06", "companyAgeYears": 13.5, "companySize": "DEMAIS",
  "primaryCnae": "6619399", "address": { "city": "SAO PAULO", "state": "SP", "zipCode": "..." },
  "partners": [{ "name": "...", "role": "Diretor", "since": "..." }], "partnersCount": 9, "error": null
}
```

Not found / invalid rows: `{"found": false, "error": "NOT_FOUND" | "INVALID_CNPJ_CHECK_DIGITS" | "SOURCES_UNAVAILABLE: ..."}`.

### How much does the CNPJ lookup cost?

Pay per event: **$0.006 per company enriched** ($6 / 1,000). Not found & invalid CNPJs = $0.

### FAQ

#### Is this CNPJ lookup legal?

Yes. CNPJ registration data is public by law and published by Receita Federal as open data. Partner CPFs are masked at the source. Use personal data (partner names, emails) in compliance with LGPD.

#### How fresh is the Receita Federal data?

As fresh as the monthly Receita Federal open-data release used by the mirrors.

#### Can I use it as a CNPJ API?

Yes. Run the Actor via the Apify API (or n8n, Make, Zapier) and read results from the dataset in JSON, CSV or Excel.

#### Which partner (QSA) fields are returned?

For each partner: `name`, `role`, `since` and `ageRange`, plus `partnersCount`.

#### What happens if a source is down?

Each lookup retries with exponential backoff on 429/5xx and then fails over to the second mirror. If both fail, the row gets `SOURCES_UNAVAILABLE` and is not charged.

#### Does it support the alphanumeric CNPJ (2026)?

Current version validates numeric CNPJs; alphanumeric support is on the roadmap.

### Related actors

- [Brazil Company Due Diligence Report by CNPJ (KYB)](https://apify.com/cairolabs/brazil-company-due-diligence) – Receita data + CEIS/CNEP sanctions + PNCP public contracts + risk level, $0.10 per report.

***

### 🇧🇷 Consulta CNPJ em lote – dados da Receita Federal (pt-BR)

Faça a **consulta CNPJ** de milhares de empresas de uma vez e receba razão social, nome fantasia, situação cadastral, CNAE principal e secundários, endereço completo, e-mail, telefones, **quadro societário (QSA / sócios)**, Simples/MEI, capital social, porte e idade da empresa. Fonte: **Dados Abertos da Receita Federal** (BrasilAPI e minhareceita.org com failover automático).

- Cole a lista ou a coluna da planilha; aceita CNPJ com ou sem máscara.
- **Você só paga por CNPJ encontrado** (US$ 0,006 por empresa — US$ 6 por 1.000). Inválidos e não encontrados não são cobrados.
- Ideal para prospecção B2B, enriquecimento de CRM, KYC/cadastro de fornecedores e análise de crédito.
- Exporte em Excel, CSV ou JSON, ou integre via API, n8n, Make e Zapier.

*Unofficial community Actor; not affiliated with Receita Federal.*

# Actor input Schema

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

Brazilian company tax IDs, with or without punctuation (33.000.167/0001-01 or 33000167000101).

## `csvText` (type: `string`):

Paste any text containing CNPJs separated by line breaks, commas, semicolons or tabs.

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

Safety cap to control cost.

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

Parallel lookups. Keep low to respect the public sources.

## `delayMs` (type: `integer`):

Per-worker pause between requests (rate limiting).

## `maxRetries` (type: `integer`):

Retries with exponential backoff on 429/5xx before failing over.

## `skipInvalid` (type: `boolean`):

If on, CNPJs with wrong check digits are not written to the dataset.

## `includeRaw` (type: `boolean`):

Adds the full original JSON under 'raw'.

## Actor input object example

```json
{
  "cnpjs": [
    "33000167000101",
    "18236120000158",
    "00000000000191"
  ],
  "maxItems": 10,
  "maxConcurrency": 3,
  "delayMs": 400,
  "maxRetries": 2,
  "skipInvalid": false,
  "includeRaw": false
}
```

# Actor output Schema

## `overview` (type: `string`):

One row per input CNPJ: company data when found, or found=false with an error code (NOT_FOUND / INVALID_CNPJ_CHECK_DIGITS / SOURCES_UNAVAILABLE).

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

All dataset items with every field.

# 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": [
        "33000167000101",
        "18236120000158",
        "00000000000191"
    ],
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("cairolabs/brazil-cnpj-enrichment").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": [
        "33000167000101",
        "18236120000158",
        "00000000000191",
    ],
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("cairolabs/brazil-cnpj-enrichment").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": [
    "33000167000101",
    "18236120000158",
    "00000000000191"
  ],
  "maxItems": 10
}' |
apify call cairolabs/brazil-cnpj-enrichment --silent --output-dataset

```

## MCP server setup

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

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/blw3ebOpiwDlB7bf1/builds/qsNc97Xsmcxc7Gq9S/openapi.json