Company Search

How to search companies by filters in the CNPJ.ws Commercial API (Premium Plan), with cursor-based pagination.

In the Commercial API, in the Premium Plan, you can perform searches using filters to find companies that meet your requirements.

Attention: Access to this endpoint is exclusive to Premium Plan subscribers.

Method: GET

Endpoint: https://comercial.cnpj.ws/v2/pesquisa?ADD_FILTERS

Filters

You can use the filters below in your queries:

Field	Description
atividade_principal_id	CNAE Code
atividade_secundaria_id	CNAE Code
atividade_id	CNAE Code (search in the primary and secondary activity)
natureza_juridica_id	Legal Nature Code
razao_social	Company Name
nome_fantasia	Trade Name
pais_id	BACEN Country Code
estado_id	IBGE State Code
cidade_id	IBGE City Code
cep	ZIP Code
situacao_cadastral	Registration status with the Federal Revenue
data_situacao_cadastral_de	Registration Status Date (From this date) in YYYY-MM-DD format
data_situacao_cadastral_ate	Registration Status Date (Until this date) in YYYY-MM-DD format
porte_id	Company size ID
socio_nome	Partner's Name
data_inicio_atividade_de	Start Date of Activity (From this date) in YYYY-MM-DD format
data_inicio_atividade_ate	Start Date of Activity (Until this date) in YYYY-MM-DD format

It is crucial to highlight that the queries made in this endpoint are based on our database and not on the Federal Revenue database. Therefore, discrepancies may occur between the information, as our database may have a lag of up to 45 days compared to the updated data from the Federal Revenue. It is worth noting that, although we perform daily registrations due to CNPJ queries made in the API, the lag can still occur.

List of Registration Statuses:

Active
Closed
Inactive
Null
Suspended

List of Registered Sizes:

ID	Description
01	Not informed
02	Micro Enterprise
03	Small Business
05	Others

Request Examples

Authorization

x_api_token<token>

Token de autenticação no header

In: header

Query Parameters

cursor?string

Cursor para a próxima página (obtido em proximo_cursor da resposta anterior). Não enviar na primeira requisição.

limite?integer

Quantidade de itens por página (1 a 100)

Range1 <= value <= 100

Default20

limit?integer

Alias para limite

Range1 <= value <= 100

atividade_principal_id?string

Código CNAE da atividade principal

atividade_secundaria_id?string

Código CNAE da atividade secundária

atividade_id?string

Código CNAE (pesquisa na atividade principal e secundária)

natureza_juridica_id?string

Código da Natureza Jurídica

razao_social?string

Razão Social (mín. 3 caracteres)

Length3 <= length

nome_fantasia?string

Nome Fantasia

pais_id?string

Código do País do BACEN

estado_id?string

Código IBGE do estado

cidade_id?string

Código IBGE da Cidade

cep?string

CEP

situacao_cadastral?string

Situação cadastral na Receita Federal

data_situacao_cadastral_de?string

Data da Situação Cadastral (a partir de) YYYY-MM-DD

Formatdate

data_situacao_cadastral_ate?string

Data da Situação Cadastral (até) YYYY-MM-DD

Formatdate

porte_id?string

Id do porte da empresa

socio_nome?string

Nome do Sócio

socio_cpf_cnpj?string

CPF ou CNPJ do Sócio (apenas dígitos)

data_inicio_atividade_de?string

Data de Início de Atividade (a partir de) YYYY-MM-DD

Formatdate

data_inicio_atividade_ate?string

Data de Início de Atividade (até) YYYY-MM-DD

Formatdate

token?string

Token de autenticação (opcional)

Header Parameters

x_api_token?string

Token de autenticação (opcional)

Response Body

`application/json`

curl -X GET "https://example.com/v2/pesquisa"

{  "paginacao": {    "limite": 20,    "total": 1523,    "tem_proxima_pagina": true,    "tem_pagina_anterior": false,    "cursor_consulta_atual": null,    "cursor_pagina_atual": "eyJ2IjoiMDAwMDAwMDAwMDAwNDIiLCJkIjoiYXNjIiwibSI6ImluYyJ9",    "proximo_cursor": "eyJ2IjoiMDAwMDAwMDAwMDAwNjciLCJkIjoiYXNjIiwibSI6ImV4YyJ9",    "cursor_anterior": null  },  "filtros_disponiveis": [    "atividade_principal_id",    "estado_id",    "cidade_id"  ],  "filtros_aplicados": {    "atividade_principal_id": "0111",    "estado_id": 35  },  "data": [    "00000000000042",    "00000000000050"  ]}

{  "statusCode": 400,  "message": "Cursor inválido: formato incorreto",  "error": "Bad Request"}

{  "status": 0,  "titulo": "string",  "detalhes": "string",  "validacao": [    "string"  ],  "statusCode": 0,  "message": "string",  "error": "string"}

{  "statusCode": 403,  "message": "Recurso não disponível para plano gratuito",  "error": "Forbidden"}

We have a package that can help you integrate with JavaScript:

yarn add consultar-cnpj

const consultarCNPJ = require("consultar-cnpj");

async function getCNPJ() {
  const token = "INFORME O SEU TOKEN DE ACESSO";
  const page = 2;

  const data = await consultarCNPJ.pesquisa(
    { atividade_principal_id: "6203100", estado_id: 28 },
    token,
    page
  );
  console.log(data);
}

More information about the package

Cursor-based Pagination

When the search returns more than 20 CNPJs, the API splits the response into multiple pages using cursor-based pagination.

The pagination information is returned in the paginacao object of the JSON response, which indicates whether there are previous or next pages and provides the cursors needed to keep navigating:

{
  "paginacao": {
    "limite": 20,
    "total": 320430,
    "tem_proxima_pagina": true,
    "tem_pagina_anterior": false,
    "cursor_consulta_atual": null,
    "cursor_pagina_atual": "eyJ2IjoiMDAwMDAwMDAwMTkxMDAiLCJkIjoiYXNjIiwibSI6ImluYyJ9",
    "proximo_cursor": "eyJ2IjoiMDAwMDAwMDA2NzI5NjMiLCJkIjoiYXNjIiwibSI6ImV4YyJ9",
    "cursor_anterior": null
  }
}

First page

On the first request you do not need to provide any cursor — the API automatically returns the first page of results.

Next page

To get the next page, use the value returned in proximo_cursor as the cursor parameter of the next request:

curl -X GET https://comercial.cnpj.ws/v2/pesquisa?cursor=eyJ2IjoiMDAwMDAwMDA2NzI5NjMiLCJkIjoiYXNjIiwibSI6ImV4YyJ9 -H "x_api_token: YOUR_TOKEN"

The next page is only available when tem_proxima_pagina is true.

Previous page

If you need to go back to the previous page, use the value of cursor_anterior:

curl -X GET https://comercial.cnpj.ws/v2/pesquisa?cursor=<cursor_anterior> -H "x_api_token: YOUR_TOKEN"

The previous page is only available when tem_pagina_anterior is true.

It is also possible to change the number of CNPJs returned, the default is 20 but it can be up to 100:

curl -X GET https://comercial.cnpj.ws/v2/pesquisa?atividade_principal_id=6203100&limite=100 -H "x_api_token: YOUR_TOKEN"

Return Example

Below is an example of the JSON returned when searching by CNAE 6203100:

{
  "paginacao": {
    "limite": 20,
    "total": 38876,
    "tem_proxima_pagina": true,
    "tem_pagina_anterior": false,
    "cursor_consulta_atual": null,
    "cursor_pagina_atual": "eyJ2IjoiMDAwMDAwMjgwMDAxMjkiLCJkIjoiYXNjIiwibSI6ImluYyJ9",
    "proximo_cursor": "eyJ2IjoiMDAwMTA2NTcwMDAyMTAiLCJkIjoiYXNjIiwibSI6ImV4YyJ9",
    "cursor_anterior": null
  },
  "filtros_disponiveis": [
    "atividade_principal_id",
    "atividade_secundaria_id",
    "atividade_id",
    "natureza_juridica_id",
    "razao_social",
    "nome_fantasia",
    "pais_id",
    "estado_id",
    "cidade_id",
    "cep",
    "situacao_cadastral",
    "data_situacao_cadastral_de",
    "data_situacao_cadastral_ate",
    "porte_id",
    "socio_nome",
    "socio_cpf_cnpj",
    "data_inicio_atividade_de",
    "data_inicio_atividade_ate"
  ],
  "filtros_aplicados": {
    "atividade_principal_id": "6203100"
  },
  "data": [
    "00000028000129",
    "00000135000157",
    "00000266000215",
    "00000342000101",
    "00000390000108",
    "00000544000153",
    "00000635000199",
    "00000664000150",
    "00001713000170",
    "00001871000120",
    "00001871000200",
    "00002440000188",
    "00003800000166",
    "00003821000181",
    "00004032000165",
    "00004387000154",
    "00007190000250",
    "00009301000186",
    "00010657000130",
    "00010657000210"
  ]
}

Company Search

200application/json

400application/json

401application/json

403application/json

Primeira página (sem cursor)

Próxima página (com cursor)

Última página

Cursor inválido

Nenhum filtro informado

Plano gratuito

Plano sem permissão de filtros

On this page

`application/json`

`application/json`

`application/json`

`application/json`