Debitado do seu saldo a cada chamada cobrada. Autenticação pelo header X-API-Key. Veja como obter a chave.
Mapeia quem está por trás de um CNPJ: o quadro de sócios e administradores (QSA) e as participações societárias (Ownership), atuais e históricas. Dois diferenciais em relação à consulta cadastral comum:
Documento completo do sócio. As consultas cadastrais públicas entregam o CPF do sócio mascarado (***123456**). Aqui o documento vem completo — é o que permite seguir a cadeia: consultar o sócio PF em sanções e mídia, ou expandir o sócio PJ em nova consulta de vínculos.
Um nível de vínculo indireto na mesma consulta. Quando uma pessoa chega à empresa através de outra empresa (ex.: sócio de uma holding que é sócia da consultada), o vínculo já vem na resposta, marcado com o caminho: nivel = "Indirect - <CNPJ intermediário> - <PAPEL>". O CNPJ do meio da string é a empresa intermediária — faça o parsing se precisar dele isolado, ou consulte-o em nova chamada para descer mais um nível.
Antes de usar, conheça o teto do dado — limites da própria origem pública, não desta consulta:
Sem percentual de participação. Nenhuma fonte pública informa quanto cada sócio detém. A consulta responde quem participa e em que papel — não quanto.
Sociedade Anônima não expõe acionistas. O registro cadastral de uma S.A. traz apenas a diretoria e os administradores — os acionistas não constam nas fontes cadastrais públicas. A cadeia completa até o beneficiário final (UBO) só é rastreável em sociedades limitadas (Ltda), cujo quadro societário é registrado integralmente. Se a consultada (ou uma intermediária da cadeia) for S.A., a rastreabilidade para na diretoria. (Companhias abertas são a exceção parcial: acionistas relevantes constam nos formulários entregues ao regulador do mercado de capitais, fora do escopo desta consulta.)
Escopo fixo: vínculos societários. A consulta devolve apenas vínculos de sociedade (QSA e participações) — vínculos de emprego e outros relacionamentos ficam fora, por definição do produto.
Sócios com vínculo direto, somando vigentes e já encerrados. Não é o tamanho de vinculosAtuais: indiretos entram na lista e não somam aqui (5 itens com totalSocios: 3 = 3 diretos + 2 indiretos), e o campo pode ser > 0 com vinculosAtuais vazio quando todos os sócios já saíram — nesse caso eles estão em vinculosHistoricos. Para saber se a lista está incompleta, use resultadoParcial.
totalControladas
Empresas em que a consultada figura como sócia/controladora, contando vínculos diretos, vigentes e encerrados.
empresaFamiliar
Sinalização de empresa familiar feita pela origem — indício para orientar a diligência, não fato registrado. Confirme pelos sobrenomes e documentos em vinculosAtuais.
temVinculoIndireto
true quando ao menos um vínculo atual é indireto — sinal de estrutura societária em camadas, para aprofundar a diligência (não é, por si, indício de irregularidade).
resultadoParcial
true quando a origem indica mais vínculos do que os retornados (quadro societário muito grande). Nesse caso trate a lista como incompleta: ela é um subconjunto, não o mapa societário fechado.
status
Resumo do resultado em uma frase, pronto para exibição.
Cada item de vinculosAtuais e vinculosHistoricos
Campo
Descrição
documento / tipoDocumento / paisDocumento
Documento completo do vinculado (CPF ou CNPJ, sem máscara), o tipo e o país de emissão. Sócio estrangeiro pode vir sem documento brasileiro.
nome
Nome completo (PF) ou razão social (PJ) do vinculado.
tipoVinculo
QSA (quadro de sócios e administradores registrado) ou Ownership (participação societária).
papel
Papel do vinculado conforme a origem, em vocabulário padronizado — ex.: SOCIO, SOCIO-ADMINISTRADOR, ADMINISTRADOR, SOCIO PESSOA JURIDICA DOMICILIADO NO EXTERIOR, REPRESENTANTE LEGAL (PESSOA JURÍDICA), DIRETOR, PROCURADOR.
nivel
Direct = vínculo direto. Indireto vem como Indirect - <CNPJ intermediário> - <PAPEL> — a string carrega o caminho da cadeia.
origemDado
De onde o vínculo foi extraído. RECEITA FEDERAL é registro oficial; outras origens são possíveis, inclusive vínculo inferido (deduzido por cruzamento, não registrado) — nesse caso trate como pista a confirmar.
dataInicio / dataFim
Entrada e saída do vínculo. dataFim vazia ("") indica vínculo vigente ou data não informada pela origem — a classificação entre atual e histórico é a da própria origem (os dois arrays), não derivada dessa data.
atualizadoEm
Última atualização do registro na origem, em ISO 8601 sem horário (yyyy-MM-dd).
CNPJ localizado e sem nenhum vínculo societário devolve 200 com vinculosAtuais: [] e vinculosHistoricos: [] — resposta válida, e cobrada. Já o 404 significa que o CNPJ não está indexado na base de vínculos: resultado inconclusivo, sem cobrança.
{
"type": "object",
"properties": {
"cnpj": {
"type": "string",
"description": "CNPJ consultado, no formato 00.000.000/0000-00."
},
"status": {
"type": "string",
"description": "Resumo do resultado em uma frase, pronto para exibição."
},
"totalSocios": {
"type": "integer",
"description": "Quantidade de sócios com vínculo DIRETO, somando os vigentes e os já encerrados. Duas consequências: (a) não é o tamanho de `vinculosAtuais` — vínculos indiretos entram na lista e não somam aqui; (b) pode ser maior que zero com `vinculosAtuais` vazio, quando todos os sócios já saíram (aí eles estão em `vinculosHistoricos`). Resultado incompleto tem campo próprio: `resultadoParcial`."
},
"vinculosAtuais": {
"type": "array",
"items": {
"type": "object",
"properties": {
"nome": {
"type": "string",
"description": "Nome completo (pessoa física) ou razão social (pessoa jurídica) do vinculado."
},
"nivel": {
"type": "string",
"description": "`Direct` = vínculo direto com a consultada. Indireto vem como `Indirect - <CNPJ intermediário> - <PAPEL>`: a string carrega o CAMINHO — o CNPJ do meio é a empresa através da qual o vínculo chega (faça o parsing se precisar dele isolado, ou consulte esse CNPJ para descer outro nível)."
},
"papel": {
"type": "string",
"description": "Papel do vinculado conforme registrado na origem, em vocabulário padronizado — ex.: `SOCIO`, `SOCIO-ADMINISTRADOR`, `ADMINISTRADOR`, `SOCIO PESSOA JURIDICA DOMICILIADO NO EXTERIOR`, `REPRESENTANTE LEGAL (PESSOA JURÍDICA)`, `DIRETOR`, `PROCURADOR`."
},
"dataFim": {
"type": "string",
"description": "Data de saída do vínculo, ISO 8601 sem horário (`yyyy-MM-dd`). Vazio (`\"\"`) quando o vínculo segue vigente ou quando a origem não informa a data."
},
"documento": {
"type": "string",
"description": "Documento do vinculado, completo e sem máscara de ocultação: CPF (000.000.000-00) ou CNPJ (00.000.000/0000-00) quando o sócio é pessoa jurídica. Pode vir em formato livre para sócio estrangeiro sem documento brasileiro."
},
"dataInicio": {
"type": "string",
"description": "Data de entrada no vínculo, ISO 8601 sem horário (`yyyy-MM-dd`). Vazio quando a origem não informa."
},
"origemDado": {
"type": "string",
"description": "De onde o vínculo foi extraído. `RECEITA FEDERAL` é registro oficial. Outras origens são possíveis, inclusive vínculo INFERIDO (deduzido por cruzamento, não registrado): nesse caso trate como pista a confirmar, não como fato cadastral."
},
"tipoVinculo": {
"type": "string",
"description": "`QSA` = consta do quadro de sócios e administradores registrado. `Ownership` = participação societária da consultada em outra empresa. Vínculos de emprego e outros tipos ficam fora desta consulta."
},
"atualizadoEm": {
"type": "string",
"description": "Data da última atualização do registro na origem, ISO 8601 sem horário (`yyyy-MM-dd`)."
},
"paisDocumento": {
"type": "string",
"description": "País de emissão do documento — ex.: Brazil."
},
"tipoDocumento": {
"type": "string",
"description": "Tipo do documento: CPF ou CNPJ. Pode vir vazio para vinculado estrangeiro."
}
}
},
"description": "Vínculos societários vigentes (QSA e participações), com o documento COMPLETO de cada vinculado — sem a máscara das consultas cadastrais públicas."
},
"empresaFamiliar": {
"type": "boolean",
"description": "Sinalização de empresa familiar feita pela origem do dado. Indício para orientar a diligência, não um fato registrado em cartório — confirme pelos sobrenomes e documentos dos sócios em `vinculosAtuais`."
},
"resultadoParcial": {
"type": "boolean",
"description": "true quando a lista devolvida pode não ser o quadro completo: a consultada tem quadro societário grande demais para uma única resposta, ou a origem aponta mais vínculos diretos do que os itens retornados. Trate como incompleto para fins de diligência."
},
"totalControladas": {
"type": "integer",
"description": "Quantidade de empresas em que a consultada figura como sócia/controladora, contando vínculos diretos, vigentes e encerrados."
},
"temVinculoIndireto": {
"type": "boolean",
"description": "true quando ao menos um vínculo ATUAL é indireto — chega à empresa consultada através de outra empresa. Sinal de estrutura societária em camadas: examine o campo `nivel` de cada vínculo para ver o caminho."
},
"vinculosHistoricos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"nome": {
"type": "string",
"description": "Nome completo (pessoa física) ou razão social (pessoa jurídica) do ex-vinculado."
},
"nivel": {
"type": "string",
"description": "`Direct` = vínculo direto com a consultada. Indireto vem como `Indirect - <CNPJ intermediário> - <PAPEL>`: a string carrega o CAMINHO — o CNPJ do meio é a empresa através da qual o vínculo chega (faça o parsing se precisar dele isolado, ou consulte esse CNPJ para descer outro nível)."
},
"papel": {
"type": "string",
"description": "Papel do vinculado conforme registrado na origem, em vocabulário padronizado — ex.: `SOCIO`, `SOCIO-ADMINISTRADOR`, `ADMINISTRADOR`, `SOCIO PESSOA JURIDICA DOMICILIADO NO EXTERIOR`, `REPRESENTANTE LEGAL (PESSOA JURÍDICA)`, `DIRETOR`, `PROCURADOR`."
},
"dataFim": {
"type": "string",
"description": "Data de encerramento do vínculo, ISO 8601 sem horário (`yyyy-MM-dd`). Pode vir vazia quando a origem classifica o vínculo como encerrado sem informar a data."
},
"documento": {
"type": "string",
"description": "Documento do ex-vinculado, completo e sem máscara: CPF (000.000.000-00) ou CNPJ (00.000.000/0000-00)."
},
"dataInicio": {
"type": "string",
"description": "Data de entrada no vínculo, ISO 8601 sem horário (`yyyy-MM-dd`). Vazio quando a origem não informa."
},
"origemDado": {
"type": "string",
"description": "De onde o vínculo foi extraído. `RECEITA FEDERAL` é registro oficial. Outras origens são possíveis, inclusive vínculo INFERIDO (deduzido por cruzamento, não registrado): nesse caso trate como pista a confirmar, não como fato cadastral."
},
"tipoVinculo": {
"type": "string",
"description": "`QSA` = consta do quadro de sócios e administradores registrado. `Ownership` = participação societária da consultada em outra empresa. Vínculos de emprego e outros tipos ficam fora desta consulta."
},
"atualizadoEm": {
"type": "string",
"description": "Data da última atualização do registro na origem, ISO 8601 sem horário (`yyyy-MM-dd`)."
},
"paisDocumento": {
"type": "string",
"description": "País de emissão do documento — ex.: Brazil."
},
"tipoDocumento": {
"type": "string",
"description": "Tipo do documento: CPF ou CNPJ. Pode vir vazio para vinculado estrangeiro."
}
}
},
"description": "Vínculos societários já encerrados, conforme classificação da origem — mesmo formato de `vinculosAtuais`. Úteis para reconstruir a linha do tempo societária da empresa."
}
}
}
Códigos de erro
Código
Mensagem
Quando acontece
400
Parâmetros inválidos para esta consulta.
CNPJ ausente, com dígito verificador inválido ou fora do formato. Máscara é aceita (00.000.000/0000-00).
401
Chave de API ausente ou inválida.
Header X-API-Key não enviado ou não reconhecido.
403
Saldo insuficiente ou acesso negado a este endpoint.
Conta sem saldo para cobrir a consulta ou sem permissão no catálogo da marca.
404
Nenhum registro localizado para o documento consultado.
O CNPJ não está indexado na base de vínculos. Resultado INCONCLUSIVO — não significa ausência de sócios. A consulta não é cobrada.
408
A consulta excedeu o tempo limite. Tente novamente.
A base de origem demorou além do orçamento de tempo da consulta.
500
Erro ao processar a consulta. Tente novamente em instantes.
Falha inesperada ao consultar a base de origem.
Quando usar
KYB e identificação de beneficiário final (UBO) — onboarding de PJ: quem são os sócios, com documento completo para prosseguir a diligência; temVinculoIndireto aponta estruturas em camadas que merecem expansão.
Due diligence de contrapartes e fornecedores — o quadro societário atual e o histórico (quem saiu e quando), para detectar trocas recentes de controle antes de contratar.
Expansão de grafo societário — o documento sem máscara permite encadear consultas: cada sócio PJ vira uma nova consulta de vínculos, cada sócio PF pode ser verificado em listas-restritivas (sanções) e midia-adversa (reputação).
PLD — o bloco societário da análise: sócios, administradores e procuradores da empresa sob avaliação, com a profundidade da cadeia explícita em nivel.
Para os dados cadastrais da própria empresa (situação, endereço, CNAE, capital social), combine com a consulta cadastral de CNPJ. Lembre-se do teto do dado: participação percentual e acionistas de S.A. não são públicos em nenhuma fonte.
Integrar
OpenAPI (JSON) ↗ — importe a URL
no Postman ou no Insomnia para gerar a coleção com todos os endpoints. Também dá para consultar
pelo chat: conecte via MCP. Esta página em Markdown.