Company Data API (CNPJ)

Integrate the CNPJ Data API using authentication via X-API-Key.

This documentation is intended for authenticated integrations and API credit usage. For a free individual lookup without login, use the Public CNPJ Lookup.

Step 1 — Buy credits

Open the CNPJ Data dashboard, go to the API section and purchase API credits.

Step 2 — Generate an API key

In the authenticated dashboard, open the My API tab, generate your key and send it in the X-API-Key.

X-API-Key: <id>.<secret>

The X-API-Key header is allowed by CORS, so the API can be called directly from the browser without a server-side proxy.

Public CNPJ lookup — no API key

GET/api/public/companies/{cnpj}

Open endpoint to look up a company by CNPJ without authentication and without consuming credits. Ideal for testing, one-off validations and prototypes.

curl -X GET \
  "https://api.cnpjdata.com.br/api/public/companies/33000167000101"

200 response (example):

{
  "cnpjCompleto": "33.000.167/0001-01",
  "razaoSocial": "PETROLEO BRASILEIRO S A PETROBRAS",
  "nomeFantasia": "PETROBRAS - EDISE",
  "situacaoCadastralRef": { "codigo": "02", "descricao": "Ativa" },
  "cnaeRef": { "codigo": "0600001", "descricao": "Extração De Petróleo E Gás Natural" },
  "municipioRef": { "codigo": "6001", "descricao": "Rio De Janeiro" },
  "uf": "RJ",
  "telefone1": "2121660000",
  "dataInicioAtividade": "1966-09-28T00:00:00.000Z",
  "socios": [
    { "nomeSocio": "A******* G***** C**** L*******", "cnpjCpfSocio": "***91******", "entrada": "29/07/2025", "descricaoQualificacao": "Diretor" }
  ]
}

Do not send the X-API-Key header: this route is public and consumes no credits. Partner identification fields are masked; for full data, list queries and advanced filters, use the authenticated endpoints below.

Malformed CNPJ or invalid check digits: 400 with code "CNPJ_INVALID". Valid but non-existent CNPJ: 404 with code "CNPJ_NOT_FOUND".

Look up a company by CNPJ

GET/api/companies/{cnpj}

curl -X GET "https://api.cnpjdata.com.br/api/companies/01234567000189" \
  -H "X-API-Key: <id>.<secret>"

Send the CNPJ without formatting, using numbers only. Cost: 1 credit.

The paid API also returns the company partner list and the data available to authenticated access. In the public lookup, partner identification fields are masked.

Public lookup example (masked data):

{
  "socios": [
    {
      "nomeSocio": "S***** M****** A****",
      "cnpjCpfSocio": "***00******",
      "entrada": "13/06/2001",
      "descricaoQualificacao": "Sócio",
      "descricaoFaixaEtaria": "51 A 60"
    }
  ]
}

Paid API example (available data):

{
  "socios": [
    {
      "nomeSocio": "SHEILA MARTINS ALVES",
      "cnpjCpfSocio": "***008208**",
      "entrada": "13/06/2001",
      "descricaoQualificacao": "Sócio",
      "descricaoFaixaEtaria": "51 A 60"
    }
  ]
}

200 response (example):

{
  "searchId": "uuid-da-busca",
  "creditsCharged": 1,
  "creditsBalance": 919,
  "cnpjCompleto": "01.234.567/0001-89",
  "razaoSocial": "EMPRESA EXEMPLO COMERCIO LTDA",
  "situacaoCadastralCodigo": "02",
  "uf": "SP"
}

Every successful query response includes creditsCharged (credits charged for that request) and creditsBalance (remaining balance after the charge; 0 when nothing is charged). Use these fields to display cost and balance in real time, without querying /credits/balance.

The full response includes the other available registration data.

View full response

{
  "searchId": "uuid-da-busca",
    "cnpjCompleto": "01.234.567/0001-89",
  "razaoSocial": "EMPRESA EXEMPLO COMERCIO LTDA",
  "nomeFantasia": "LOJA EXEMPLO",
  "naturezaJuridicaCodigo": "2135",
  "porteEmpresaCodigo": "01",
  "situacaoCadastralCodigo": "02",
  "cnaeFiscalPrincipalCodigo": "4781400",
  "cnaeFiscalSecundariaCodigo": "4755502,4772500,4782201,4761003",
  "codMunicipio": "4729",
  "matrizFilialCodigo": "1",
  "logradouro": "RUA EXEMPLO 1",
  "numero": "100",
  "complemento": "LOJA 01",
  "bairro": "CENTRO",
  "cep": "01000000",
  "uf": "SP",
  "telefone1": null,
  "telefone2": null,
  "email": null,
  "dataInicioAtividade": "1997-01-21T00:00:00.000Z",
  "dataSituacaoCadastral": "2005-11-03T00:00:00.000Z",
  "anoInicio": 1997,
  "naturezaJuridicaRef": {
    "codigo": "2135",
    "descricao": "Empresário (Individual)"
  },
  "porteEmpresaRef": {
    "codigo": "01",
    "descricao": "{copy.microCompany}"
  },
  "situacaoCadastralRef": {
    "codigo": "02",
    "descricao": "{copy.activeStatus}"
  },
  "cnaeRef": {
    "codigo": "4781400",
    "descricao": "Comércio Varejista De Artigos Do Vestuário E Acessórios"
  },
  "municipioRef": {
    "codigo": "4729",
    "descricao": "Jordania"
  },
  "matrizFilialRef": {
    "codigo": "1",
    "descricao": "Matriz"
  },
  "cnaesSecundarios": [
    {
      "codigo": "4755502",
      "descricao": "Comercio Varejista De Artigos De Armarinho"
    }
  ],
  "socios": [
    {
      "nomeSocio": "SHEILA MARTINS ALVES",
      "cnpjCpfSocio": "***008208**",
      "entrada": "13/06/2001",
      "descricaoQualificacao": "Sócio",
      "descricaoFaixaEtaria": "51 A 60"
    }
  ]
}

Look up two or more companies using a CNPJ list

POST/api/companies/list

curl -X POST "https://api.cnpjdata.com.br/api/companies/list" \
  -H "X-API-Key: <id>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{"cnpjs":["01234567000189","00987654000110"],"page":1,"limit":20}'

Full list export:

curl -X POST "https://api.cnpjdata.com.br/api/companies/list" \
  -H "X-API-Key: <id>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{"cnpjs":["02204106000132","19131243000197"],"export":true}'

200 response (example):

{
  "searchId": null,
  "data": [{ "cnpjCompleto": "01.234.567/0001-89", "razaoSocial": "EMPRESA EXEMPLO LTDA" }],
  "page": 1,
  "limit": 20,
  "total": 2,
  "totalPages": 1,
  "creditsCharged": 2,
  "creditsBalance": 918
}

Without page, the query defaults to page=1 and only the returned records are charged. To generate a file with all records, send "export": true in the body: the total is charged and the file is associated with the searchId.

The cnpjs field is required and cannot be empty (400 "CNPJS_REQUIRED"). Every CNPJ is validated, including check digits; any invalid CNPJ rejects the entire request with 400 "CNPJ_INVALID".

Response with export=true (same as the synchronous filter export; creditsCharged = list total):

{
  "searchId": "uuid-da-busca",
  "data": [{ "cnpjCompleto": "02.204.106/0001-32", "razaoSocial": "EMPRESA EXEMPLO LTDA" }],
  "page": 1,
  "limit": 20,
  "total": 2,
  "totalPages": 1,
  "creditsCharged": 2,
  "creditsBalance": 916
}

Validation error examples:

{ "code": "CNPJS_REQUIRED", "message": "Envie uma lista de CNPJs não vazia." }

{ "code": "CNPJ_INVALID", "message": "2 CNPJ(s) inválido(s) na lista. Corrija e reenvie.",
  "invalidCnpjs": ["11111111111111", "123"], "invalidCount": 2 }

View full company model

{
  "cnpjCompleto": "01.234.567/0001-89",
  "razaoSocial": "EMPRESA EXEMPLO COMERCIO LTDA",
  "nomeFantasia": "LOJA EXEMPLO",
  "naturezaJuridicaCodigo": "2135",
  "porteEmpresaCodigo": "01",
  "situacaoCadastralCodigo": "02",
  "cnaeFiscalPrincipalCodigo": "4781400",
  "cnaeFiscalSecundariaCodigo": "4755502,4772500,4782201,4761003",
  "codMunicipio": "4729",
  "matrizFilialCodigo": "1",
  "logradouro": "RUA EXEMPLO 1",
  "numero": "100",
  "complemento": "LOJA 01",
  "bairro": "CENTRO",
  "cep": "01000000",
  "uf": "SP",
  "telefone1": null,
  "telefone2": null,
  "email": null,
  "dataInicioAtividade": "1997-01-21T00:00:00.000Z",
  "dataSituacaoCadastral": "2005-11-03T00:00:00.000Z",
  "anoInicio": 1997,
  "naturezaJuridicaRef": {
    "codigo": "2135",
    "descricao": "Empresário (Individual)"
  },
  "porteEmpresaRef": {
    "codigo": "01",
    "descricao": "{copy.microCompany}"
  },
  "situacaoCadastralRef": {
    "codigo": "02",
    "descricao": "{copy.activeStatus}"
  },
  "cnaeRef": {
    "codigo": "4781400",
    "descricao": "Comércio Varejista De Artigos Do Vestuário E Acessórios"
  },
  "municipioRef": {
    "codigo": "4729",
    "descricao": "Jordania"
  },
  "matrizFilialRef": {
    "codigo": "1",
    "descricao": "Matriz"
  },
  "cnaesSecundarios": [
    {
      "codigo": "4755502",
      "descricao": "Comercio Varejista De Artigos De Armarinho"
    }
  ],
  "socios": [
    {
      "nomeSocio": "SHEILA MARTINS ALVES",
      "cnpjCpfSocio": "***008208**",
      "entrada": "13/06/2001",
      "descricaoQualificacao": "Sócio",
      "descricaoFaixaEtaria": "51 A 60"
    }
  ]
}

Check the company count before a filtered query

Before running a large filtered query, check how many companies match the selected criteria. This lets you assess the volume before requesting the data.

GET/api/companies/count

curl -X GET "https://api.cnpjdata.com.br/api/companies/count?uf=SP&cidadeNome=Campinas&cnae=6201500&porte=05&status=02&anoInicio=2016" \
  -H "X-API-Key: <id>.<secret>"

200 response:

{ "count": 123456 }

page and limit are not used. This route does not return companies, create a searchId or consume credits.

Filter examples

Filters can be combined in the URL. Accepted parameters: uf, codMunicipio, cidadeNome, cnae, porte, status, anoInicio, anoInicioMin e anoInicioMax.

Location and period

Use uf=SP and cidadeNome=Campinas to filter by location. For a specific year, use anoInicio=2016. For a range, use anoInicioMin=2015&anoInicioMax=2020.

CNAE

Enter the complete CNAE code using numbers only. Do not use dots, hyphens or slashes. Example: cnae=6201500.

Status

Enter the code in the status parameter. Example: status=02 for active companies.

Company size

Code	Description
00	Not informed
01	Micro company
03	Small company
05	Other

Registration status

Code	Description
01	Null
02	Active
03	Suspended
04	Unfit
08	Closed

Search by filters — full export

GET/api/companies

Send export=true to generate a file with all matching records. Without export=true, the query is always paginated (without page it defaults to page=1), creates no file and never shows up in My searches.

curl -X GET "https://api.cnpjdata.com.br/api/companies?uf=SP&cidadeNome=Campinas&cnae=6201500&porte=05&status=02&anoInicio=2016&export=true" \
  -H "X-API-Key: <id>.<secret>"

With export=true, the page parameter is ignored.

200 response (summary):

{
  "searchId": "uuid-da-busca",
  "data": [{ "cnpjCompleto": "01.234.567/0001-89", "razaoSocial": "EMPRESA EXEMPLO LTDA" }],
  "page": 1,
  "limit": 20,
  "total": 58,
  "totalPages": 3,
  "creditsCharged": 58,
  "creditsBalance": 861
}

Up to 10,000 records: the export is synchronous. The response brings a sample of the records in data (respecting limit) and the complete file is already available for download via the searchId. The total records are charged.

Above 10,000 records: the file is generated asynchronously. The response comes with "status": "processing" and empty data, the total credits are charged upfront and the file becomes available via the searchId once processing completes (usually within a few minutes, proportional to the volume).

Response when the export is asynchronous (above 10,000 records):

{
  "searchId": "uuid-da-busca",
  "status": "processing",
  "data": [],
  "page": 1,
  "limit": 20,
  "total": 123456,
  "totalPages": 6173,
  "creditsCharged": 123456,
  "creditsBalance": 0
}

The full response contains the available registration data. Billing is based on the total records found; the file is associated with the searchId.

View full company model

{
  "cnpjCompleto": "01.234.567/0001-89",
  "razaoSocial": "EMPRESA EXEMPLO COMERCIO LTDA",
  "nomeFantasia": "LOJA EXEMPLO",
  "naturezaJuridicaCodigo": "2135",
  "porteEmpresaCodigo": "01",
  "situacaoCadastralCodigo": "02",
  "cnaeFiscalPrincipalCodigo": "4781400",
  "cnaeFiscalSecundariaCodigo": "4755502,4772500,4782201,4761003",
  "codMunicipio": "4729",
  "matrizFilialCodigo": "1",
  "logradouro": "RUA EXEMPLO 1",
  "numero": "100",
  "complemento": "LOJA 01",
  "bairro": "CENTRO",
  "cep": "01000000",
  "uf": "SP",
  "telefone1": null,
  "telefone2": null,
  "email": null,
  "dataInicioAtividade": "1997-01-21T00:00:00.000Z",
  "dataSituacaoCadastral": "2005-11-03T00:00:00.000Z",
  "anoInicio": 1997,
  "naturezaJuridicaRef": {
    "codigo": "2135",
    "descricao": "Empresário (Individual)"
  },
  "porteEmpresaRef": {
    "codigo": "01",
    "descricao": "{copy.microCompany}"
  },
  "situacaoCadastralRef": {
    "codigo": "02",
    "descricao": "{copy.activeStatus}"
  },
  "cnaeRef": {
    "codigo": "4781400",
    "descricao": "Comércio Varejista De Artigos Do Vestuário E Acessórios"
  },
  "municipioRef": {
    "codigo": "4729",
    "descricao": "Jordania"
  },
  "matrizFilialRef": {
    "codigo": "1",
    "descricao": "Matriz"
  },
  "cnaesSecundarios": [
    {
      "codigo": "4755502",
      "descricao": "Comercio Varejista De Artigos De Armarinho"
    }
  ],
  "socios": [
    {
      "nomeSocio": "SHEILA MARTINS ALVES",
      "cnpjCpfSocio": "***008208**",
      "entrada": "13/06/2001",
      "descricaoQualificacao": "Sócio",
      "descricaoFaixaEtaria": "51 A 60"
    }
  ]
}

Track an asynchronous export

After an asynchronous export, track the processing by its searchId:

GET/api/companies/exports/{searchId}/status

curl -X GET "https://api.cnpjdata.com.br/api/companies/exports/<searchId>/status" \
  -H "X-API-Key: <id>.<secret>"

200 response (example):

{
  "searchId": "uuid-da-busca",
  "status": "processing",
  "total": 123456,
  "error": null,
  "createdAt": "2026-08-31T14:30:00.000Z"
}

We recommend polling the status every 5–10 seconds while it is "processing".

Status	Meaning
processing	File being generated
ready	Ready for download
failed	Processing failed; the charged credits are automatically refunded

Download the result file via API

When the status is "ready", download the file by its searchId. The route is authenticated with X-API-Key and closes the fully programmatic loop: export → status polling → download.

GET/api/companies/exports/{searchId}/download

curl -X GET "https://api.cnpjdata.com.br/api/companies/exports/<searchId>/download" \
  -H "X-API-Key: <id>.<secret>"

200 response (example):

{
  "url": "https://bucket.s3.amazonaws.com/api-search/uuid-da-busca.json?X-Amz-Signature=...",
  "expiresAt": "2026-09-29T22:32:00.000Z",
  "remainingDownloads": 4
}

The link returned in url is valid for 2 minutes — download it right away. The remainingDownloads field shows how many downloads are left today for this result (out of 5).

Possible errors: 404 "NOT_FOUND" (search result not found), 400 "BAD_REQUEST" (still processing) and 400 "BAD_REQUEST" (daily limit of 5 downloads for this result reached).

Search by filters — pagination with page

GET/api/companies

Send page and limit to request only one page. Without page, the query defaults to page=1.

The limit parameter accepts 1 to 100: values above 100 return 400 "LIMIT_EXCEEDED" (no silent truncation). An invalid page (0, negative or non-integer) returns 400 "INVALID_PAGE".

curl -X GET "https://api.cnpjdata.com.br/api/companies?uf=SP&cidadeNome=Campinas&cnae=6201500&porte=05&status=02&anoInicioMin=2015&anoInicioMax=2020&page=2&limit=20" \
  -H "X-API-Key: <id>.<secret>"

200 response (summary):

{
  "searchId": null,
  "data": [{ "cnpjCompleto": "12.345.678/0001-99", "uf": "SP" }],
  "page": 2,
  "limit": 20,
  "total": 58,
  "totalPages": 3,
  "creditsCharged": 20,
  "creditsBalance": 919
}

Billing is based only on the number of records returned on the page. Paginated queries return "searchId": null, create no file and never show up in My searches.

Need every record matching a filter? Use export=true: same cost as paginating through everything, but with a complete file, an e-mail notification and the asynchronous mode above 10k. Pagination is for browsing and sampling.

View full company model

{
  "cnpjCompleto": "01.234.567/0001-89",
  "razaoSocial": "EMPRESA EXEMPLO COMERCIO LTDA",
  "nomeFantasia": "LOJA EXEMPLO",
  "naturezaJuridicaCodigo": "2135",
  "porteEmpresaCodigo": "01",
  "situacaoCadastralCodigo": "02",
  "cnaeFiscalPrincipalCodigo": "4781400",
  "cnaeFiscalSecundariaCodigo": "4755502,4772500,4782201,4761003",
  "codMunicipio": "4729",
  "matrizFilialCodigo": "1",
  "logradouro": "RUA EXEMPLO 1",
  "numero": "100",
  "complemento": "LOJA 01",
  "bairro": "CENTRO",
  "cep": "01000000",
  "uf": "SP",
  "telefone1": null,
  "telefone2": null,
  "email": null,
  "dataInicioAtividade": "1997-01-21T00:00:00.000Z",
  "dataSituacaoCadastral": "2005-11-03T00:00:00.000Z",
  "anoInicio": 1997,
  "naturezaJuridicaRef": {
    "codigo": "2135",
    "descricao": "Empresário (Individual)"
  },
  "porteEmpresaRef": {
    "codigo": "01",
    "descricao": "{copy.microCompany}"
  },
  "situacaoCadastralRef": {
    "codigo": "02",
    "descricao": "{copy.activeStatus}"
  },
  "cnaeRef": {
    "codigo": "4781400",
    "descricao": "Comércio Varejista De Artigos Do Vestuário E Acessórios"
  },
  "municipioRef": {
    "codigo": "4729",
    "descricao": "Jordania"
  },
  "matrizFilialRef": {
    "codigo": "1",
    "descricao": "Matriz"
  },
  "cnaesSecundarios": [
    {
      "codigo": "4755502",
      "descricao": "Comercio Varejista De Artigos De Armarinho"
    }
  ],
  "socios": [
    {
      "nomeSocio": "SHEILA MARTINS ALVES",
      "cnpjCpfSocio": "***008208**",
      "entrada": "13/06/2001",
      "descricaoQualificacao": "Sócio",
      "descricaoFaixaEtaria": "51 A 60"
    }
  ]
}

Download the result file

Open the authenticated dashboard, go to My API searches, find the search by its label and click Download — or use the API download route above.

The link is valid for 2 minutes, and the same result can be downloaded up to 5 times per day (dashboard and API share the same limit).

Searches still in processing become available for download as soon as the status changes to ready.

The dashboard listing shows the status and the total number of records for each search. Only these appear there: individual CNPJ lookups, exports (synchronous and asynchronous) and list queries in export mode — paginated queries create no history.

Errors and response codes

Every error response uses the { "code": "...", "message": "..." } envelope. Switch on the code field; message is human-readable text for display. Some validations include extra fields beyond the envelope (e.g. invalidCnpjs and invalidCount for list CNPJ_INVALID) — treat code as primary and extras as context.

HTTP	Code	When it occurs
400	CNPJ_INVALID	Malformed CNPJ or invalid check digits (includes the public route)
404	CNPJ_NOT_FOUND	Valid CNPJ, but not present in the database
400	CNPJS_REQUIRED	Empty or missing CNPJ list in POST /companies/list
400	INVALID_PAGE · INVALID_LIMIT · LIMIT_EXCEEDED	Invalid pagination (INVALID_PAGE, INVALID_LIMIT or LIMIT_EXCEEDED)
400	API_CREDITS_INSUFFICIENT	Insufficient credit balance
401	API_KEY_*	API key problems (missing, invalid, etc.)
429	RATE_LIMITED	Rate limit exceeded