Consulta a árvore de relacionamentos

curl --request POST \
  --url https://api.jusfy.dev/calculators/api/v1/consultas/relacionamentos \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "document": "52998224725"
}
'

import requests

url = "https://api.jusfy.dev/calculators/api/v1/consultas/relacionamentos"

payload = { "document": "52998224725" }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({document: '52998224725'})
};

fetch('https://api.jusfy.dev/calculators/api/v1/consultas/relacionamentos', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.jusfy.dev/calculators/api/v1/consultas/relacionamentos",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'document' => '52998224725'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "statusCode": 200,
  "message": "Consulta concluída com sucesso",
  "timestamp": "2026-07-28T18:00:00.000Z",
  "path": "/api/v1/consultas/relacionamentos",
  "result": {
    "personal_data": {
      "document": "52998224725",
      "document_type": "CPF",
      "name": "MARIA DE SOUZA SILVA",
      "mother_name": "ANTONIA ALVES DE SOUZA",
      "birthdate": "12/12/1995",
      "age": 30,
      "gender": "F",
      "phones": [
        {
          "phone": "(61) 991234567"
        },
        {
          "phone": "(61) 32654987"
        },
        {
          "phone": "(61) 998765432"
        }
      ],
      "emails": [
        {
          "email": "maria.silva@exemplo.com.br"
        }
      ],
      "addresses": [
        {
          "address": "null QD 12 CJ O C 12 C 1 2",
          "neighborhood": "PARANOA",
          "city": "BRASILIA",
          "state": "DF",
          "zipcode": 71571215
        },
        {
          "address": "null QD 31 CJ H CS 25",
          "neighborhood": "PARANOA",
          "city": "BRASILIA",
          "state": "DF",
          "zipcode": 71573108
        },
        {
          "address": " QD 20 1",
          "neighborhood": "PARANOA",
          "city": "BRASILIA",
          "state": "DF",
          "zipcode": "71572020"
        }
      ],
      "relatives": [
        {
          "document": "",
          "name": "ANTONIA ALVES DE SOUZA",
          "relationship_type": "MÃE"
        }
      ],
      "business_partners": [],
      "companies": [
        {
          "document": "11222333000181",
          "name": "11.222.333 MARIA DE SOUZA SILVA",
          "relationship_start_date": "26/05/2023",
          "relationship_end_date": "Atual",
          "relationship_type": "OWNER"
        }
      ]
    }
  }
}

Consultas

Consulta a árvore de relacionamentos

Retorna a rede de relacionamentos de um CPF ou CNPJ.

Para CPF, os dados cadastrais do titular (nome, filiação, nascimento, contatos e endereços) mais os parentes, os sócios e as empresas dele. Para CNPJ, os dados cadastrais da empresa mais os relacionamentos societários em dois níveis (sócios e empresas do 1º nível, e os deles no 2º).

É a consulta mais demorada da API: são vários fornecedores encadeados por requisição. Prever até 4 minutos de espera.

POST

api

consultas

relacionamentos

Consulta a árvore de relacionamentos

curl --request POST \
  --url https://api.jusfy.dev/calculators/api/v1/consultas/relacionamentos \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "document": "52998224725"
}
'

import requests

url = "https://api.jusfy.dev/calculators/api/v1/consultas/relacionamentos"

payload = { "document": "52998224725" }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({document: '52998224725'})
};

fetch('https://api.jusfy.dev/calculators/api/v1/consultas/relacionamentos', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.jusfy.dev/calculators/api/v1/consultas/relacionamentos",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'document' => '52998224725'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "statusCode": 200,
  "message": "Consulta concluída com sucesso",
  "timestamp": "2026-07-28T18:00:00.000Z",
  "path": "/api/v1/consultas/relacionamentos",
  "result": {
    "personal_data": {
      "document": "52998224725",
      "document_type": "CPF",
      "name": "MARIA DE SOUZA SILVA",
      "mother_name": "ANTONIA ALVES DE SOUZA",
      "birthdate": "12/12/1995",
      "age": 30,
      "gender": "F",
      "phones": [
        {
          "phone": "(61) 991234567"
        },
        {
          "phone": "(61) 32654987"
        },
        {
          "phone": "(61) 998765432"
        }
      ],
      "emails": [
        {
          "email": "maria.silva@exemplo.com.br"
        }
      ],
      "addresses": [
        {
          "address": "null QD 12 CJ O C 12 C 1 2",
          "neighborhood": "PARANOA",
          "city": "BRASILIA",
          "state": "DF",
          "zipcode": 71571215
        },
        {
          "address": "null QD 31 CJ H CS 25",
          "neighborhood": "PARANOA",
          "city": "BRASILIA",
          "state": "DF",
          "zipcode": 71573108
        },
        {
          "address": " QD 20 1",
          "neighborhood": "PARANOA",
          "city": "BRASILIA",
          "state": "DF",
          "zipcode": "71572020"
        }
      ],
      "relatives": [
        {
          "document": "",
          "name": "ANTONIA ALVES DE SOUZA",
          "relationship_type": "MÃE"
        }
      ],
      "business_partners": [],
      "companies": [
        {
          "document": "11222333000181",
          "name": "11.222.333 MARIA DE SOUZA SILVA",
          "relationship_start_date": "26/05/2023",
          "relationship_end_date": "Atual",
          "relationship_type": "OWNER"
        }
      ]
    }
  }
}

Autorizações

x-api-key

string

header

obrigatório

Corpo

application/json

document

string

obrigatório

CPF ou CNPJ do titular, com ou sem máscara. Separadores (incluindo a barra do CNPJ) são aceitos e ignorados. O dígito verificador é validado antes da consulta. O formato do resultado depende do documento: CPF devolve personal_data, CNPJ devolve company_data.

Exemplo:

"52998224725"

Resposta

O formato depende do documento consultado: CPF devolve personal_data (o exemplo abaixo), CNPJ devolve company_data, com outro conjunto de campos — nunca os dois, e nunca nenhum (sem dado é erro). Datas vêm em DD/MM/AAAA, não em ISO. Pontos de atenção, todos confirmados em captura real: (1) em business_partners/companies, relationship_end_date pode ser a string Atual no lugar de uma data, quando o vínculo está vigente, e relationship_type vem cru do fornecedor, em inglês (ex.: OWNER); (2) addresses[].address costuma começar com a string literal "null " — o campo junta tipo de logradouro + endereço, e o tipo falta na maioria dos cadastros (na captura, oito de dez endereços); limpe o prefixo antes de exibir; (3) addresses[].zipcode vem number em alguns itens e string em outros, no mesmo array; (4) relatives só traz dez tipos de parentesco, já traduzidos para pt-BR (MÃE, FILHO(a)…) — o que o fornecedor manda fora dessa lista é descartado —, o document do parente pode vir vazio, e a mãe aparece duas vezes (aqui e em mother_name); (5) age vem 0 também quando não foi possível calcular a idade. No CNPJ, relationships.has_more_relationships: true significa que havia mais de 100 relacionamentos de 1º nível e as listas foram truncadas em 100, e relationship_end_date de cada vínculo é sempre null — quem indica vínculo encerrado é is_finished.

The response is of type object.

Comece aqui

Fundamentos

Produtos

Referência

Consulta a árvore de relacionamentos

Autorizações

Corpo

Resposta