# CNPJ.ws

> CNPJ.ws is an API (Application Programming Interface) for querying data of Brazilian legal entities through the CNPJ (Cadastro Nacional da Pessoa Jurídica). It returns public company data in JSON format, making it easy to integrate with any software. Keep your suppliers' and customers' data always up to date by consulting the complete data of any company using its CNPJ.

The API is developed and maintained by Bitize, a startup born in the Sorocaba Technology Park, which uses this data in BitERP, its AI-powered ERP, to find and approve suppliers for its clients.

Key facts:

- **Data source**: CNPJ.ws periodically fetches data from public agencies such as the Receita Federal (Federal Revenue), SEFAZ, Sintegra, and Suframa, enriching its database and delivering relevant, updated information in an organized and fast manner.
- **Detailed information**: Partners (sócios), branches (estabelecimentos), addresses, Simples Nacional, MEI, state registrations (inscrições estaduais), Suframa registrations, economic activities (CNAE), legal nature, company size, tax regimes (available from 2021 onward), registration status, and more.
- **Two API tiers**: a free Public API (`https://publica.cnpj.ws/`) and a token-authenticated Commercial API (`https://comercial.cnpj.ws/`, authenticated with the `x_api_token` header).
- **Operations**: query a CNPJ, query all establishments by the CNPJ root (first 8 digits), search companies by filters, validate a Suframa registration, and check monthly request consumption.
- **Company search filters** (Premium plan only): search companies by state, city, CNAE, registration status, and state registration, with cursor-based pagination.
- **Rate limits**: the free Public API allows up to 3 queries per minute per IP, returning HTTP 429 when exceeded. Paid plans have a general limit of 2,000 requests per minute plus a monthly query quota; after the contracted monthly limit is reached, queries continue but are capped at 4 per minute. Monthly limits do not accumulate into following periods.
- **Consumption notifications**: the API sends emails when consumption reaches 80%, 90%, and 100% of the monthly quota.
- **Billing**: charges are monthly, with a Service Invoice (Nota Fiscal de Serviço) issued for each charge after payment. Monthly, semi-annual, and annual billing cycles are available.
- **Alphanumeric CNPJ**: the API is already prepared for the alphanumeric CNPJ format, whose first registrations are expected in July 2026.
- **Languages**: the site is available in Portuguese (pt-BR, default), English (en-US), and Spanish (es-ES) under locale-prefixed URLs. The documentation is available in Portuguese (default), English (`/en`), and Spanish (`/es`).

## Documentation

- [CNPJ.ws Documentation — llms.txt](https://docs.cnpj.ws/llms.txt): Full machine-readable index of the CNPJ.ws documentation, including data models, API reference, and guides. **Start here for API details.**
- [CNPJ.ws Documentation — llms-full.txt](https://docs.cnpj.ws/llms-full.txt): The complete documentation content in a single file.
- [Documentation home](https://docs.cnpj.ws/en): Overview, data models, API reference, and integration guides.
- [Commercial API reference](https://docs.cnpj.ws/en/referencia-de-api/api-comercial): Token-authenticated API with CNPJ lookup, CNPJ root lookup, company search, Suframa validation, and usage monitoring.
- [Querying a CNPJ (Commercial API)](https://docs.cnpj.ws/en/referencia-de-api/api-comercial/consultando-cnpj): How to query a CNPJ authenticating with the `x_api_token` header.
- [Querying by CNPJ root](https://docs.cnpj.ws/en/referencia-de-api/api-comercial/consultando-raiz-cnpj): How to retrieve all establishments of a company from the first 8 digits of the CNPJ.
- [Company search](https://docs.cnpj.ws/en/referencia-de-api/api-comercial/pesquisa-de-empresas): How to search companies by filters (Premium plan), with cursor-based pagination.
- [Monthly consumption](https://docs.cnpj.ws/en/referencia-de-api/api-comercial/consultando-consumo): How to check the number of monthly requests already made.
- [Suframa validation](https://docs.cnpj.ws/en/referencia-de-api/api-comercial/validando-inscricao-suframa): How to validate a Suframa registration by CNPJ using the POST method.
- [Public API reference](https://docs.cnpj.ws/en/referencia-de-api/api-publica): Free API for basic CNPJ consultation and Suframa validation.
- [Querying a CNPJ (Public API)](https://docs.cnpj.ws/en/referencia-de-api/api-publica/consultando-cnpj): How to query a CNPJ with the GET method, up to 3 requests per minute.
- [Public API limitations](https://docs.cnpj.ws/en/referencia-de-api/api-publica/limitacoes): Rate limits and restrictions of the free tier.
- [Data models](https://docs.cnpj.ws/en/modelos-de-dados): Reference for establishments, partners, economic activities, states, cities, countries, legal natures, company sizes, tax regimes, registration statuses, and more.
- [Error messages](https://docs.cnpj.ws/en/modelos-de-dados/mensagens-erro): Error codes and responses returned by the API.
- [Changelog](https://docs.cnpj.ws/en/changelog): API and documentation change history.

## Site

- [Home (English)](https://www.cnpj.ws/en-US): Product overview, free CNPJ lookup, plans, and FAQ.
- [Home (Portuguese)](https://www.cnpj.ws/pt-BR): Versão em português.
- [Home (Spanish)](https://www.cnpj.ws/es-ES): Versión en español.
- [Client Portal](https://app.cnpj.ws): Sign in to manage your subscription, API tokens, and usage.
- [GitHub](https://github.com/cnpj-ws): Official CNPJ.ws repositories and code samples.

## Resources

- [Insomnia collection (JSON)](https://www.cnpj.ws/insomnia.json): Ready-to-import request collection covering the Public and Commercial API endpoints.
- [Insomnia collection (YAML)](https://www.cnpj.ws/insomnia.yaml): The same collection in YAML format.
- [Excel spreadsheet](https://www.cnpj.ws/ConsultaDadosEmpresariaisViaCNPJws.zip): Spreadsheet that queries company data through the CNPJ.ws API.

## Integration guides

- [Consult CNPJ with Javascript and Node.js](https://docs.cnpj.ws/en/blog/consultar-cnpj-javascript)
- [Consult CNPJ with PHP](https://docs.cnpj.ws/en/blog/consulta-cnpj-php)
- [Consult CNPJ with Java](https://docs.cnpj.ws/en/blog/consultar-cnpj-java)
- [Consult CNPJ with ADVPL (Protheus)](https://docs.cnpj.ws/en/blog/integracao-protheus)
- [Protheus trigger for CNPJ lookup](https://docs.cnpj.ws/en/blog/gatilho-consultar-cnpj)
- [Consult CNPJ for free with Excel](https://docs.cnpj.ws/en/blog/consultar-cnpj-excel)
- [Automate customer registration with a CNPJ API](https://docs.cnpj.ws/en/blog/how-to-automate-customer-registration-with-a-cnpj-api)
- [Keep customer and supplier records up to date](https://docs.cnpj.ws/en/blog/manter-clientes-fornecedores-atualizados)

## Background

- [What is the CNPJ](https://docs.cnpj.ws/en/blog/o-que-e-cnpj): The Cadastro Nacional de Pessoa Jurídica is the registry used by the Receita Federal to open an institution, with or without profit purposes.
- [Alphanumeric CNPJ](https://docs.cnpj.ws/en/blog/alphanumeric-cnpj): How to calculate the check digits of the alphanumeric CNPJ.
- [Test alphanumeric CNPJ](https://docs.cnpj.ws/en/blog/alphanumeric-cnpj-test-example): Example for adapting your application ahead of the July 2026 rollout.
- [The CNPJ.ws project](https://docs.cnpj.ws/en/blog/cnpjws): A fast, free API with public data on Brazilian companies, a by-product of the Bitize platform.

## Legal

- [Terms of Use](https://www.cnpj.ws/en-US/termos-de-uso)
- [Privacy Policy](https://www.cnpj.ws/en-US/politicas-de-privacidade)
- [Service Level Agreement (SLA)](https://www.cnpj.ws/en-US/acordo-de-nivel-de-servico)

Data returned by CNPJ.ws is public and non-confidential, and its disclosure complies with Decree No. 8.777/2016 and Law No. 12.527/2011, which ensure the constitutional right of access to information, while respecting the individual right to privacy.

## Contact

- Email: contato@cnpj.ws
- Address: Rua Eugênio Rabello, 98, Jardim Embaixador, Sorocaba-SP, Brazil
- Legal entity: C D TIRABASSI JUNIOR TECNOLOGIA DA INFORMAÇÃO LTDA — CNPJ 42.064.856/0001-70
- Parent company: [Bitize](https://www.bitize.com.br)
- Related product: [BitERP](https://www.biterp.ai) — AI-powered ERP that consumes CNPJ.ws data