# BrasilAPI CNPJ Company Scraper (`automation-lab/brasilapi-cnpj-company-scraper`) Actor Enrich Brazilian CNPJ numbers with legal names, status, CNAE, address, contacts, partners, Simples/MEI flags, and source metadata. - **URL**: https://apify.com/automation-lab/brasilapi-cnpj-company-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Business - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ## BrasilAPI CNPJ Company Scraper Enrich Brazilian company CNPJ numbers with public BrasilAPI registry data. Turn a list of CNPJs into clean company records with legal names, trade names, registration status, CNAE activity, address, contact fields, Simples/MEI tax flags, share capital, and QSA partner data. ### What does BrasilAPI CNPJ Company Scraper do? BrasilAPI CNPJ Company Scraper is an Apify Actor for Brazilian company registry enrichment. It calls the public BrasilAPI CNPJ endpoint for each CNPJ you provide. It normalizes the response into a consistent dataset that is ready for export, CRM enrichment, compliance screening, and analytics. Use it when you already have Brazilian CNPJ numbers and need structured company details at scale. ### Who is it for? 🧾 Compliance teams use it to enrich supplier and customer CNPJs before KYB checks. 🏒 B2B sales teams use it to add firmographic fields to Brazilian lead lists. πŸ“Š Data teams use it to normalize company registry data for warehouses and BI tools. πŸ›’ Procurement teams use it to validate supplier registration status and legal entity details. βš™οΈ RevOps teams use it to enrich CRM accounts from CNPJ lists. ### Why use this actor? The actor is built for repeatable enrichment workflows. It accepts formatted or digits-only CNPJs. It deduplicates values inside each run to avoid unnecessary API traffic. It saves typed rows for both successful and failed lookups. It includes bounded retry logic for temporary BrasilAPI errors. It does not require browser automation, login, cookies, or a private API key. ### Data you can extract | Field group | Examples | | --- | --- | | Identity | CNPJ, formatted CNPJ, legal name, trade name | | Status | registration status, status reason, opening date | | Activity | main CNAE code, main CNAE description, secondary CNAEs | | Firmographics | legal nature, company size, share capital, headquarters flag | | Address | street, number, complement, district, city, state, ZIP, country | | Contact | phone 1, phone 2, fax, email | | Tax flags | Simples option, MEI option, option dates | | Partners | QSA count and optional partner records | | Metadata | source URL, scrape timestamp, raw response option | ### How much does it cost to enrich CNPJ company data? This actor uses pay-per-event pricing. You pay a small run start fee and a per-record event for each CNPJ row saved to the dataset. The default input is intentionally small so your first run stays inexpensive. Larger batches get lower tier prices according to the Apify pricing tier shown on the actor page. ### Input Provide a list of Brazilian CNPJ values. Formatted values are accepted. Digits-only values are accepted. Duplicate CNPJs are processed once per run. Example input: ```json { "cnpjs": [ "19.131.243/0001-97", "00.000.000/0001-91", "60.746.948/0001-12" ], "maxItems": 100, "includePartners": true, "includeRawData": false, "maxConcurrency": 3 } ```` ### Input options `cnpjs` is the main required field. `maxItems` limits how many unique CNPJs are processed. `includePartners` controls whether QSA partner records are included. `includeRawData` attaches the original BrasilAPI JSON object for custom mapping. `maxConcurrency` controls how many requests run in parallel. `maxRetries` controls retry attempts for 429, 5xx, and network errors. `retryDelayMillis` controls the base retry delay. ### Output Each dataset row represents one processed CNPJ. Successful rows include normalized company data. Failed rows include `success=false`, the HTTP status when available, and an error message. Example output item: ```json { "requestedCnpj": "19.131.243/0001-97", "cnpj": "19131243000197", "cnpjFormatted": "19.131.243/0001-97", "success": true, "legalName": "OPEN KNOWLEDGE BRASIL", "tradeName": "REDE PELO CONHECIMENTO LIVRE", "registrationStatus": "ATIVA", "mainActivityDescription": "Atividades de associaçáes de defesa de direitos sociais", "addressCity": "SAO PAULO", "addressState": "SP", "sourceUrl": "https://brasilapi.com.br/api/cnpj/v1/19131243000197" } ``` ### Tips for best results Use digits-only CNPJs when exporting from a database. Keep concurrency conservative for very large batches. Turn on `includeRawData` only when you need fields that are not normalized yet. Use `success=false` rows to clean invalid CNPJs in your source system. Run smaller scheduled batches if you need daily enrichment. ### Common workflows Enrich a CRM export with legal company names and addresses. Validate supplier CNPJs before onboarding. Build a Brazilian company master data table. Check registration status for customer due diligence. Append CNAE activity descriptions to sales lead lists. Review QSA partner data for KYB triage. ### Integrations Export dataset items as CSV for spreadsheets. Send JSON results to a data warehouse. Connect Apify datasets to Make or Zapier. Call the actor from a backend service using the Apify API. Schedule recurring CNPJ enrichment runs from Apify. ### API usage with Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/brasilapi-cnpj-company-scraper').call({ cnpjs: ['19131243000197', '00000000000191'], includePartners: true }); console.log(run.defaultDatasetId); ``` ### API usage with Python ```python from apify_client import ApifyClient import os client = ApifyClient(os.environ['APIFY_TOKEN']) run = client.actor('automation-lab/brasilapi-cnpj-company-scraper').call(run_input={ 'cnpjs': ['19131243000197', '00000000000191'], 'includePartners': True, }) print(run['defaultDatasetId']) ``` ### API usage with cURL ```bash curl -X POST "https://api.apify.com/v2/acts/automation-lab~brasilapi-cnpj-company-scraper/runs?token=$APIFY_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"cnpjs":["19131243000197","00000000000191"],"includePartners":true}' ``` ### MCP usage Use this actor from AI tools through Apify MCP. Claude Code MCP URL: `https://mcp.apify.com/?tools=automation-lab/brasilapi-cnpj-company-scraper` Add it to Claude Code with: ```bash claude mcp add apify-brasilapi-cnpj --transport http "https://mcp.apify.com/?tools=automation-lab/brasilapi-cnpj-company-scraper" ``` Claude Desktop can use this JSON MCP server configuration: ```json { "mcpServers": { "apify-brasilapi-cnpj": { "url": "https://mcp.apify.com/?tools=automation-lab/brasilapi-cnpj-company-scraper" } } } ``` Example prompts: - "Enrich these CNPJs and summarize which companies are active." - "Convert this supplier list into a table with legal name, state, CNAE, and status." - "Check which CNPJs failed validation and explain why." ### Scheduling You can schedule this actor for recurring enrichment. For example, run it daily with newly collected CNPJs from your CRM. Store the resulting dataset ID for downstream processing. Use a fixed input list for periodic supplier status checks. ### Error handling Invalid CNPJ checksums are saved as failure rows. BrasilAPI not-found responses are saved as failure rows. Temporary 429 and 5xx responses are retried. Network errors are retried and then saved as failure rows if they persist. This makes batch processing easier because one bad CNPJ does not stop the whole run. ### Legality and source This actor uses BrasilAPI's public CNPJ endpoint. You are responsible for using the data according to applicable laws, contracts, and privacy obligations. Do not use the actor to make decisions that require additional legal, financial, or compliance review without appropriate controls. ### FAQ #### Do I need a BrasilAPI key? No. The actor uses the public BrasilAPI CNPJ endpoint. #### Can I submit formatted CNPJs? Yes. Values like `19.131.243/0001-97` are accepted. #### What happens to duplicate CNPJs? Duplicates are processed once per run. #### Why did a row return `success=false`? The CNPJ may be invalid, not found, temporarily unavailable, or blocked by an upstream API error. Check `statusCode` and `errorMessage`. #### Should I enable raw data? Enable `includeRawData` only when you need the complete original BrasilAPI object. It increases dataset size. ### Related scrapers Use other `automation-lab` actors when you need company enrichment outside Brazil. Use lead generation actors when you need to discover companies first. Use this actor when you already have CNPJs and need registry enrichment. ### Support If a field returned by BrasilAPI is missing from the normalized output, enable `includeRawData` and contact support with an example CNPJ. If you see many 429 responses, lower concurrency and retry later. ### Changelog Initial version: CNPJ lookup, normalized company fields, QSA partner option, typed failure rows, and retry controls. # Actor input Schema ## `cnpjs` (type: `array`): Brazilian CNPJ numbers to enrich. Formatted and digits-only values are accepted. Duplicates are processed once per run. ## `maxItems` (type: `integer`): Safety cap for the number of unique CNPJs requested from BrasilAPI. ## `includePartners` (type: `boolean`): Include the QSA partner/shareholder array when BrasilAPI returns it. ## `includeRawData` (type: `boolean`): Attach the original BrasilAPI JSON object to successful records for debugging or custom downstream mapping. ## `maxConcurrency` (type: `integer`): Parallel BrasilAPI requests. Keep conservative to respect the public API. ## `maxRetries` (type: `integer`): Retry attempts for network errors, HTTP 429, and temporary 5xx responses. ## `retryDelayMillis` (type: `integer`): Base delay between retry attempts. The actor applies a simple increasing backoff. ## Actor input object example ```json { "cnpjs": [ "19.131.243/0001-97", "00.000.000/0001-91", "60.746.948/0001-12" ], "maxItems": 3, "includePartners": true, "includeRawData": false, "maxConcurrency": 3, "maxRetries": 2, "retryDelayMillis": 1000 } ``` # Actor output Schema ## `overview` (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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "cnpjs": [ "19.131.243/0001-97", "00.000.000/0001-91", "60.746.948/0001-12" ], "maxItems": 3, "includePartners": true, "includeRawData": false, "maxConcurrency": 3, "maxRetries": 2, "retryDelayMillis": 1000 }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/brasilapi-cnpj-company-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "cnpjs": [ "19.131.243/0001-97", "00.000.000/0001-91", "60.746.948/0001-12", ], "maxItems": 3, "includePartners": True, "includeRawData": False, "maxConcurrency": 3, "maxRetries": 2, "retryDelayMillis": 1000, } # Run the Actor and wait for it to finish run = client.actor("automation-lab/brasilapi-cnpj-company-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("πŸ’Ύ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).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", "00.000.000/0001-91", "60.746.948/0001-12" ], "maxItems": 3, "includePartners": true, "includeRawData": false, "maxConcurrency": 3, "maxRetries": 2, "retryDelayMillis": 1000 }' | apify call automation-lab/brasilapi-cnpj-company-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/brasilapi-cnpj-company-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "BrasilAPI CNPJ Company Scraper", "description": "Enrich Brazilian CNPJ numbers with legal names, status, CNAE, address, contacts, partners, Simples/MEI flags, and source metadata.", "version": "0.1", "x-build-id": "kRhaYUmzmUmsR0Zch" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~brasilapi-cnpj-company-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-brasilapi-cnpj-company-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/automation-lab~brasilapi-cnpj-company-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-brasilapi-cnpj-company-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/automation-lab~brasilapi-cnpj-company-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-brasilapi-cnpj-company-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "cnpjs" ], "properties": { "cnpjs": { "title": "CNPJ numbers", "type": "array", "description": "Brazilian CNPJ numbers to enrich. Formatted and digits-only values are accepted. Duplicates are processed once per run.", "items": { "type": "string" } }, "maxItems": { "title": "Maximum unique CNPJs", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Safety cap for the number of unique CNPJs requested from BrasilAPI.", "default": 100 }, "includePartners": { "title": "Include QSA / partners", "type": "boolean", "description": "Include the QSA partner/shareholder array when BrasilAPI returns it.", "default": true }, "includeRawData": { "title": "Include raw BrasilAPI response", "type": "boolean", "description": "Attach the original BrasilAPI JSON object to successful records for debugging or custom downstream mapping.", "default": false }, "maxConcurrency": { "title": "Maximum concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "Parallel BrasilAPI requests. Keep conservative to respect the public API.", "default": 3 }, "maxRetries": { "title": "Maximum retries", "minimum": 0, "maximum": 5, "type": "integer", "description": "Retry attempts for network errors, HTTP 429, and temporary 5xx responses.", "default": 2 }, "retryDelayMillis": { "title": "Retry delay (ms)", "minimum": 100, "maximum": 30000, "type": "integer", "description": "Base delay between retry attempts. The actor applies a simple increasing backoff.", "default": 1000 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```