# Brazil CNPJ Lookup — Bulk Company Data Enrichment (`joaosbp/cnpj-enrichment-lookup-br`) Actor Consulta CNPJ em lote and enrich Brazilian company data with legal name, status, CNAE, address, phones, QSA summary, tax regime, and CRM-ready lead fields. - **URL**: https://apify.com/joaosbp/cnpj-enrichment-lookup-br.md - **Developed by:** [João Victor](https://apify.com/joaosbp) (community) - **Categories:** Lead generation, Automation, Business - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## 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 ## Brazil CNPJ Lookup — Bulk Company Data Enrichment **Bulk CNPJ lookup for Brazilian company records with CNAE, registration status, address, phones, QSA summary, tax regime, and CRM-ready fields. Também oferece consulta CNPJ em lote com erros isolados por item.** Turn a spreadsheet of CNPJs into clean company profiles with legal name, trade name, active status, CNAE, address, phones, partner summary, tax-regime signal, and a simple lead score. ### Verified batch behavior - 12 inputs tested: 10 real companies, 1 formatted duplicate, and 1 checksum-valid nonexistent CNPJ. - 10 useful enrichments, duplicate removed, and nonexistent CNPJ isolated as an item error. - Run remained `SUCCEEDED`; no masked CPF field was emitted. - Approximately `$0.0000224` platform cost per useful enrichment in the verified batch. ### Why not call BrasilAPI directly? For a one-off developer lookup, calling BrasilAPI directly is appropriate. This Actor is useful when you need batch input, formatted/unformatted normalization, deduplication, controlled concurrency, retries, per-item error isolation, Apify Datasets, schedules, webhooks, and no-code integrations. BrasilAPI remains the single upstream provider, so provider outages or policy changes can interrupt enrichment. ### At a glance | Capability | Output | |---|---| | CNPJ normalization | `cnpj`, `formattedCnpj` | | Company identity | `legalName`, `tradeName`, `legalNature` | | Registration status | `status`, `isActive`, `openingDate` | | B2B segmentation | `mainCnae`, `secondaryCnaes`, `companySize`, `shareCapital` | | Location | `address.uf`, `municipality`, `cep`, `fullAddress` | | Public contact fields | `phones`, `email` when available in source | | Public QSA summary | `partnerSummary.count`, names, qualifications | | Lead prioritization | `leadScore` 0-100 + `leadTier` | ### Best for - Brazilian B2B sales agencies - SDR and outbound teams - CRM enrichment builders - Compliance/onboarding operations - Data automation builders using Make, n8n, Zapier - SaaS founders selling to Brazilian SMBs ### What this Actor does 1. Accepts formatted or unformatted CNPJ numbers. 2. Normalizes and deduplicates values. 3. Looks up public company registration data through BrasilAPI. 4. Converts raw payloads into CRM-ready records. 5. Handles per-CNPJ failures without failing the whole run. 6. Writes clean JSON rows to an Apify Dataset. ### Example input ```json { "cnpjs": [ "19.131.243/0001-97", "33.000.167/0001-01" ], "maxItems": 10, "maxConcurrency": 3, "includePartners": true, "includeTaxRegime": true } ```` ### Example output ```json { "cnpj": "19131243000197", "formattedCnpj": "19.131.243/0001-97", "legalName": "OPEN KNOWLEDGE BRASIL", "tradeName": "REDE PELO CONHECIMENTO LIVRE", "status": "ATIVA", "isActive": true, "mainCnae": { "code": 9430800, "description": "Atividades de associações de defesa de direitos sociais" }, "address": { "uf": "SP", "municipality": "SAO PAULO", "cep": "01311902" }, "phones": ["1123851939"], "partnerSummary": { "count": 1, "names": ["HAYDEE SVAB"], "qualifications": ["Presidente"] }, "leadScore": 70, "leadTier": "MEDIUM", "source": "brasilapi" } ``` ### Use cases - Enrich CRM leads from CNPJ spreadsheets. - Validate whether companies are active before sales or onboarding. - Segment Brazilian accounts by CNAE, UF, municipality, porte, legal nature, and status. - Combine with **Website Email & Contact Finder** for company + contact lead profiles. - Export structured company data to Sheets, CRM, Make, n8n, Zapier, or BI dashboards. ### Data source and safety - Uses public company registration data through BrasilAPI. - Does **not** log in, bypass systems, scrape private portals, or require cookies. - Emits only structured public company data returned by the source. - Masked CPF values from QSA payloads are **not emitted**. - You can disable partner names with `includePartners: false`. ### Source constraints - BrasilAPI is currently the only upstream provider; no fallback provider is configured. - Provider outages, limits, or policy changes can interrupt enrichment. - Do not use this Actor to brute-force CNPJ numbers, enumerate the national database, or perform full-database scans. - Use conservative concurrency and process only CNPJs required for a legitimate workflow. ### API usage Run through Apify API, CLI, Tasks, Schedules, webhooks, Make, n8n, Zapier, or your own backend. # Actor input Schema ## `cnpjs` (type: `array`): Brazilian CNPJ numbers to enrich. Accepts formatted or unformatted values, e.g. 19.131.243/0001-97 or 19131243000197. ## `maxItems` (type: `integer`): Safety limit for how many CNPJs are processed in one run. ## `maxConcurrency` (type: `integer`): Maximum number of CNPJ lookups processed in parallel. Keep moderate to respect public API limits. ## `maxRetries` (type: `integer`): Number of retry attempts for transient network, timeout, 429, or 5xx errors. ## `requestTimeoutSecs` (type: `integer`): Maximum time in seconds to wait for each public CNPJ API request. ## `includePartners` (type: `boolean`): Include public QSA partner names and qualifications when provided by the source. Masked CPF values are never emitted. ## `includeTaxRegime` (type: `boolean`): Include latest public tax-regime summary when provided by the source. ## `source` (type: `string`): Public data source used for lookup. BrasilAPI is the default public API source. ## Actor input object example ```json { "cnpjs": [ "19.131.243/0001-97", "11.222.333/0001-81" ], "maxItems": 10, "maxConcurrency": 3, "maxRetries": 2, "requestTimeoutSecs": 20, "includePartners": true, "includeTaxRegime": true, "source": "brasilapi" } ``` # Actor output Schema ## `datasetItems` (type: `string`): Structured CNPJ enrichment records. ## `summary` (type: `string`): Counts of processed, emitted, active, and failed CNPJ lookups. # 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", "11.222.333/0001-81" ] }; // Run the Actor and wait for it to finish const run = await client.actor("joaosbp/cnpj-enrichment-lookup-br").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", "11.222.333/0001-81", ] } # Run the Actor and wait for it to finish run = client.actor("joaosbp/cnpj-enrichment-lookup-br").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", "11.222.333/0001-81" ] }' | apify call joaosbp/cnpj-enrichment-lookup-br --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=joaosbp/cnpj-enrichment-lookup-br", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Brazil CNPJ Lookup — Bulk Company Data Enrichment", "description": "Consulta CNPJ em lote and enrich Brazilian company data with legal name, status, CNAE, address, phones, QSA summary, tax regime, and CRM-ready lead fields.", "version": "0.1", "x-build-id": "6P6LYb8cdvBsNGY37" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/joaosbp~cnpj-enrichment-lookup-br/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-joaosbp-cnpj-enrichment-lookup-br", "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/joaosbp~cnpj-enrichment-lookup-br/runs": { "post": { "operationId": "runs-sync-joaosbp-cnpj-enrichment-lookup-br", "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/joaosbp~cnpj-enrichment-lookup-br/run-sync": { "post": { "operationId": "run-sync-joaosbp-cnpj-enrichment-lookup-br", "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": "CNPJs", "type": "array", "description": "Brazilian CNPJ numbers to enrich. Accepts formatted or unformatted values, e.g. 19.131.243/0001-97 or 19131243000197.", "items": { "type": "string" } }, "maxItems": { "title": "Maximum CNPJs per run", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Safety limit for how many CNPJs are processed in one run.", "default": 10 }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "Maximum number of CNPJ lookups processed in parallel. Keep moderate to respect public API limits.", "default": 3 }, "maxRetries": { "title": "Maximum retries", "minimum": 0, "maximum": 5, "type": "integer", "description": "Number of retry attempts for transient network, timeout, 429, or 5xx errors.", "default": 2 }, "requestTimeoutSecs": { "title": "Request timeout seconds", "minimum": 5, "maximum": 60, "type": "integer", "description": "Maximum time in seconds to wait for each public CNPJ API request.", "default": 20 }, "includePartners": { "title": "Include partner summary", "type": "boolean", "description": "Include public QSA partner names and qualifications when provided by the source. Masked CPF values are never emitted.", "default": true }, "includeTaxRegime": { "title": "Include tax regime summary", "type": "boolean", "description": "Include latest public tax-regime summary when provided by the source.", "default": true }, "source": { "title": "Data source", "enum": [ "brasilapi" ], "type": "string", "description": "Public data source used for lookup. BrasilAPI is the default public API source.", "default": "brasilapi" } } }, "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 } } } } } } } } } } ```