Identity lookup
CNPJ lookup
Official company registry data for a 14-digit CNPJ.
/openapi/v3/consultas/cnpj/{cnpj}token, timestamp and sign signature headers, see Authentication.Returns company registry data for a 14-digit corporate tax number: legal name, trade name, registration status, legal nature, CNAE activity code, registered address, contacts, share capital and Simples Nacional and MEI options.
The response is a bare object with no platform envelope. The field table lists every possible field; when the source holds no data for a field it comes back empty, and such fields are left out of the example. GET request: the signed body is the empty string and the CNPJ is part of the signed path.
Path parameters
cnpj* | string | CNPJ |
* Required field
ni | string | CNPJ |
tipoEstabelecimento | string | Establishment type |
nomeEmpresarial | string | Legal name |
nomeFantasia | string | Trade name |
| object | Registration status |
| object | Legal nature |
dataAbertura | string | Incorporation date |
| object | Main CNAE |
| object | Registered address |
| object | Tax jurisdiction municipality |
| array | Phone numbers |
correioEletronico | string | E-mail address |
capitalSocial | number | Share capital |
porte | string | Company size code |
situacaoEspecial | string | Special status |
dataSituacaoEspecial | string | Special status date |
opcaoSimples | bool | Simples option |
opcaoMei | bool | MEI option |
| array | Secondary activities |
dataReferencia | string | Reference date |
opcaoSimples and opcaoMei can prefill optanteSimplesNacional and mei in Register company. Have the user confirm before sending:
opcaoMei | opcaoSimples | Prefill | CRT |
|---|---|---|---|
true | true or false | mei=true, optanteSimplesNacional=true | 4 MEI |
false | true | mei=false, optanteSimplesNacional=true | 1 Simples Nacional; if over the sublimit, switch to 2 in the console |
false | false | mei=false, optanteSimplesNacional=false | 3 Regime Normal |
| Either one empty | Do not prefill; ask the user | — |
Both fields come from the registry snapshot of dataReferencia, not from a real-time lookup: joining or leaving Simples after that date does not show yet. Being over the sublimit does not show in the public data. See "Tax regime" in Companies.
What this lookup does not return. It returns no state registration (IE) and does not tell Lucro Presumido from Lucro Real. The IE lives in the company record: sent as inscricaoEstadual at registration, or obtained from SEFAZ by automatic registration. Lucro Presumido or Real is the PIS/COFINS regime, set in the console.
Format and check-digit errors (10016010, 10016011) are rejected locally by the platform: they consume no quota and are not billed. Authentication-layer errors (401 / 403 / 429) use the platform envelope; see the error model in Identity lookup.
tipoEstabelecimentoEstablishment type
| Values | Meaning |
|---|---|
| 1 | Headquarters |
| 2 | Branch |
situacaoCadastral.codigoRegistration status
| Values | Meaning |
|---|---|
| 1 | Void |
| 2 | Active |
| 3 | Suspended |
| 4 | Unfit |
| 8 | Closed |
naturezaJuridica.codigoLegal nature
4 digits, for example 2062 limited company. The first digit gives the group; the full list is the legal nature table of CONCLA / IBGE.
| Values | Meaning |
|---|---|
| 1xxx | Public administration |
| 2xxx | Business entities |
| 3xxx | Non-profit entities |
| 4xxx | Natural persons |
| 5xxx | International organizations and other extraterritorial institutions |
cnaePrincipal.codigoMain economic activity
Long list, not reproduced here: see the CNAE table at CONCLA / IBGE.
| Values | Meaning |
|---|---|
| NNNNNNN | 7 digits without punctuation, for example 6201501 |
endereco.municipio.codigo / municipioJurisdicao.codigoMunicipality code
This is the Receita Federal municipality code, not the 7-digit IBGE code used for issuing; to issue, use the name in descricao with uf.
| Values | Meaning |
|---|---|
| NNNN | 4 digits, for example 7107 São Paulo |
endereco.ufAddress state
| Values | Meaning |
|---|---|
| AC | Acre |
| AL | Alagoas |
| AP | Amapá |
| AM | Amazonas |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito Federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MT | Mato Grosso |
| MS | Mato Grosso do Sul |
| MG | Minas Gerais |
| PA | Pará |
| PB | Paraíba |
| PR | Paraná |
| PE | Pernambuco |
| PI | Piauí |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RS | Rio Grande do Sul |
| RO | Rondônia |
| RR | Roraima |
| SC | Santa Catarina |
| SP | São Paulo |
| SE | Sergipe |
| TO | Tocantins |
| EX | Abroad; foreign company holding a CNPJ |
endereco.pais.codigoCountry code
Central Bank country table, the same used by the NF-e.
| Values | Meaning |
|---|---|
| 1058 | Brazil |
| NNNN | Another country, code of up to 4 digits |
porteCompany size
Receita Federal code, passed through as received from the registry.
| Values | Meaning |
|---|---|
| 00 | Not informed |
| 01 | Micro-enterprise |
| 03 | Small company |
| 05 | Other companies |
| Code | HTTP | |
|---|---|---|
| 10016010 | 400 | Invalid CNPJ format (14 digits required). Check for stray formatting characters. |
| 10016011 | 400 | Invalid CNPJ check digits. Validate locally with the mod-11 algorithm first. |
| 10016012 | 400 | CNPJ not found. No such CNPJ in the official registry. |
| 10016020 | 503 | Upstream data source is temporarily unavailable. Retry with exponential backoff (start at 1 s, double up to 30 s, add jitter); contact the platform if it persists. |
