Skip to main content
A consulta de pessoa jurídica permite buscar dados vinculados a um CNPJ, combinando um ou mais datasets em uma única chamada. Ela pode ser usada para validação cadastral, análise de risco, prospecção, compliance, análise de crédito, cobrança, antifraude e automação de fluxos operacionais.

​
Endpoint

POST /v1/search/company

​
Entrada

A consulta utiliza o CNPJ como identificador principal. 
{
  "tax_id": "00000000000000",
  "mode": "sync",
  "datasets": [
    "company_basic_data"
  ],
  "additional_data": {}
}
CampoTipoObrigatórioDescrição
tax_idstringSimCNPJ consultado. Pode ser enviado com ou sem pontuação.
modestringNãoDefine o modo da consulta. Aceita sync ou async.
datasetsarray<string>SimLista de datasets que serão executados.
additional_dataobjectNãoDados adicionais exigidos por datasets específicos.

​
Modo de execução

A consulta pode ser executada em dois modos.
ModoDescrição
syncA API aguarda o processamento e retorna o resultado na própria resposta.
asyncA API registra a consulta para processamento assíncrono e retorna um identificador para acompanhamento posterior.

​
Status assíncronos

Consultas assíncronas podem passar pelos seguintes status:
StatusDescrição
processingA consulta foi recebida e está em processamento.
completedA consulta foi concluída com sucesso.
failedA consulta falhou e não pôde ser concluída.
partialA consulta foi concluída, mas um ou mais datasets retornaram erro.
expiredO resultado da consulta não está mais disponível.

​
Dados adicionais

Alguns datasets podem exigir parâmetros complementares. Esses dados devem ser enviados em additional_data, usando o identificador do dataset como chave. 
{
  "tax_id": "00000000000000",
  "mode": "sync",
  "datasets": [
    "company_example_dataset"
  ],
  "additional_data": {
    "company_example_dataset": {
      "reference_date": "2026-06-21",
      "state": "SP",
      "city": "São Paulo"
    }
  }
}
O exemplo acima usa um dataset fictício apenas para demonstrar a estrutura de envio de dados adicionais.

​
Ambiente de teste

A consulta de pessoa jurídica tem suporte ao ambiente de teste. Para saber como habilitar chamadas de teste, consulte:

Ambiente de teste

Veja como usar o header de sandbox e validar integrações sem consumir saldo.

​
Datasets

Os datasets disponíveis podem variar conforme plano, permissões e configuração comercial da conta.
A lista real de datasets deve ser consultada na configuração da conta ou no endpoint de datasets disponíveis.
Alguns campos de um dataset podem não ser retornados em determinadas consultas. Isso pode ocorrer por ausência da informação na base, regra de disponibilidade do provedor, restrição legal ou característica do próprio registro consultado.

​
Retorno síncrono

Quando mode for sync, a resposta retorna os dados processados em result e os metadados da consulta em query. 
{
  "code": 200,
  "message": "Consulta realizada com sucesso.",
  "result": {
    "company_basic_data": {
      "tax_id": "00000000000000",
      "legal_name": "EMPRESA EXEMPLO LTDA",
      "trade_name": "EMPRESA EXEMPLO",
      "status": "ATIVA",
      "opening_date": "2015-08-20"
    }
  },
  "query": {
    "id": "00000000-0000-0000-0000-000000000000",
    "timing": {
      "datasets": {
        "company_basic_data": 0.38
      },
      "total": 0.44
    },
    "error": {},
    "datasets_status": {
      "company_basic_data": "completed"
    },
    "datetime": "2026-06-21T09:00:00-03:00"
  }
}
CampoTipoDescrição
resultobjectDados retornados pelos datasets executados.
query.idstringIdentificador da consulta.
query.timing.datasetsobjectTempo de execução de cada dataset, em segundos.
query.timing.totalnumberTempo total da consulta, em segundos.
query.errorobjectErros individuais por dataset, quando houver.
query.datasets_statusobjectStatus individual de cada dataset executado.
query.datetimestringData e hora da consulta em formato ISO.
O campo query.error permite identificar falhas parciais sem invalidar necessariamente toda a consulta.

​
Exemplo com erro parcial

{
  "code": 200,
  "message": "Consulta realizada com sucesso.",
  "result": {
    "company_basic_data": {
      "tax_id": "00000000000000",
      "legal_name": "EMPRESA EXEMPLO LTDA"
    }
  },
  "query": {
    "id": "00000000-0000-0000-0000-000000000000",
    "timing": {
      "datasets": {
        "company_basic_data": 0.31,
        "company_quod_score": 2.52
      },
      "total": 2.63
    },
    "error": {
      "company_quod_score": {
        "code": 42025,
        "message": "Não foi possível consultar o provedor da consulta."
      }
    },
    "datasets_status": {
      "company_basic_data": "completed",
      "company_quod_score": "failed"
    },
    "datetime": "2026-06-21T09:00:00-03:00"
  }
}

​
Retorno assíncrono

Quando mode for async, a resposta retorna os dados necessários para acompanhar a consulta. 
{
  "code": 202,
  "message": "Consulta recebida para processamento.",
  "result": {
    "id": "00000000-0000-0000-0000-000000000000",
    "status": "processing"
  }
}

​
Regras importantes

  • O CNPJ deve ser válido.
  • Datasets indisponíveis, inativos ou não permitidos para a conta podem retornar erro.
  • Consultas com múltiplos datasets podem retornar resultados parciais caso algum dataset falhe.
  • A cobrança é calculada com base nos datasets efetivamente executados, conforme as regras comerciais da conta.
  • Alguns dados podem estar indisponíveis por regra legal, restrição de privacidade ou ausência de informação na base.

​
Próximos passos

Pessoa física

Veja como consultar dados vinculados a CPF.

Códigos de erro

Consulte os erros relacionados a consultas.