> ## Documentation Index
> Fetch the complete documentation index at: https://docs.judit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Dados Cadastrais por CPF, CNPJ ou Nome

> Obtenha dados cadastrais (Pessoa Física ou Jurídica) de forma síncrona pelo endpoint /entities da Judit API. Suporta consulta no datalake ou em tempo real na Receita Federal (on-demand).

export const EndpointBadges = ({auth = true, billing = "billable", flow = "sync", attachments = false, requiresVault = false}) => <div style={{
  marginTop: "-8px",
  marginBottom: "16px",
  display: "flex",
  flexWrap: "wrap",
  alignItems: "center",
  gap: "8px"
}}>
    {auth && <Badge color="gray">🔒 Requer api-key</Badge>}{" "}
    {billing === "billable" && <Badge color="yellow">💰 Cobrança por requisição</Badge>}{" "}
    {billing === "free" && <Badge color="green">✅ Grátis</Badge>}{" "}
    {billing === "on-demand" && <Badge color="purple">⚡ On-demand (preço diferenciado)</Badge>}{" "}
    {flow === "async" && <Badge color="blue">⏳ Assíncrono · webhook ou polling</Badge>}{" "}
    {flow === "sync" && <Badge color="green">⚡ Síncrono</Badge>}{" "}
    {attachments && <Badge color="purple">📎 Suporta with_attachments</Badge>}{" "}
    {requiresVault && <Badge color="red">🔑 Cofre de Credenciais</Badge>}
  </div>;

export const EntityAnimation = () => <iframe sandbox="allow-scripts" scrolling="no" style={{
  width: '100%',
  height: '540px',
  border: 'none',
  borderRadius: '12px',
  display: 'block',
  margin: '20px 0'
}} srcDoc={`<!doctype html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{width:100%;height:100%;overflow:hidden;background:#090c0d}canvas{display:block;width:100%;height:100%}</style></head><body><canvas id="c"></canvas><script>(function(){
var A='#4FD1C5',J='#1FC16B',R='#8B5CF6',M='#7A8599';
var BG='#090c0d',TXT='#e5e7eb',NF='#111827',PT='#0a1020';
var TOTAL=13.0;
var XP={app:0.13,judit:0.50,rf:0.87};
var NW=88,NH=42;
var NODES=[{id:'app',label:'Sua App',col:A},{id:'judit',label:'Judit API',col:J},{id:'rf',label:'Receita Federal',col:R}];
var STEPS=[
  {sep:true,label:'Requisição 1 — Datalake',yp:0.29},
  {fr:'app',to:'judit',label:'POST /entities',note:'{search_type:"cpf"}',col:A,ts:0.5,te:1.3,yp:0.37},
  {fr:'judit',to:'app',label:'200 {entity}',note:'datalake',col:J,ts:1.8,te:2.6,yp:0.46},
  {sep:true,label:'Requisição 2 — On-Demand (Receita Federal)',yp:0.56},
  {fr:'app',to:'judit',label:'POST /entities',note:'{on_demand: true}',col:A,ts:3.8,te:4.6,yp:0.63},
  {fr:'judit',to:'rf',label:'consulta RF',note:'em tempo real',col:R,ts:5.1,te:5.9,yp:0.71},
  {fr:'rf',to:'judit',label:'dados atualizados',note:'',col:J,ts:6.4,te:7.2,yp:0.79},
  {fr:'judit',to:'app',label:'200 {entity}',note:'on_demand: true',col:J,ts:7.7,te:8.5,yp:0.87}
];
var cv=document.getElementById('c');
function setup(){var dpr=Math.min(window.devicePixelRatio||1,2),r=cv.getBoundingClientRect(),W=r.width||window.innerWidth,H=r.height||window.innerHeight;cv.width=Math.max(1,W*dpr);cv.height=Math.max(1,H*dpr);var ctx=cv.getContext('2d');ctx.setTransform(dpr,0,0,dpr,0,0);return{ctx:ctx,w:W,h:H};}
function ease(t){return t<0.5?2*t*t:1-Math.pow(-2*t+2,2)/2;}
function rr(ctx,x,y,w,h,r){ctx.beginPath();ctx.moveTo(x+r,y);ctx.arcTo(x+w,y,x+w,y+h,r);ctx.arcTo(x+w,y+h,x,y+h,r);ctx.arcTo(x,y+h,x,y,r);ctx.arcTo(x,y,x+w,y,r);ctx.closePath();}
function gx(n,w){return n==='app'?w*XP.app:n==='judit'?w*XP.judit:w*XP.rf;}
function eg(fr,to,w){var fx=gx(fr,w),tx=gx(to,w),d=tx>fx?1:-1;return{x1:fx+d*NW/2,x2:tx-d*NW/2,d:d};}
function dPkt(ctx,x,y,lbl,col){var pw=Math.max(36,lbl.length*6+14),ph=20;ctx.save();ctx.shadowColor=col;ctx.shadowBlur=18;rr(ctx,x-pw/2,y-ph/2,pw,ph,5);ctx.fillStyle=col;ctx.fill();ctx.shadowBlur=0;ctx.fillStyle=PT;ctx.font='bold 9px monospace';ctx.textAlign='center';ctx.textBaseline='middle';ctx.fillText(lbl,x,y+0.5);ctx.restore();}
function draw(ctx,w,h,t){
  var ct=t%TOTAL,bx1=w*0.02,bx2=w*0.98;
  ctx.fillStyle=BG;ctx.fillRect(0,0,w,h);
  var nodeY=h*0.21,inF2=ct>=3.5;
  ctx.save();ctx.fillStyle='rgba(79,209,197,0.05)';rr(ctx,bx1,h*0.26,bx2-bx1,h*0.26,6);ctx.fill();ctx.restore();
  ctx.save();ctx.fillStyle='rgba(139,92,246,0.05)';rr(ctx,bx1,h*0.53,bx2-bx1,h*0.41,6);ctx.fill();ctx.restore();
  ctx.fillStyle=J;ctx.font='bold 12px Inter,system-ui,sans-serif';ctx.textAlign='center';ctx.textBaseline='middle';ctx.fillText('Consulta de Dados Cadastrais',w/2,h*0.04);
  ctx.fillStyle=M;ctx.font='10px Inter,system-ui,sans-serif';ctx.fillText('Datalake ou Receita Federal em tempo real',w/2,h*0.09);
  for(var i=0;i<NODES.length;i++){var n=NODES[i],lx=gx(n.id,w),la=(n.id==='rf'&&!inF2)?0.07:0.35;ctx.save();ctx.strokeStyle=n.col;ctx.globalAlpha=la;ctx.lineWidth=1;ctx.setLineDash([4,7]);ctx.beginPath();ctx.moveTo(lx,nodeY+NH/2);ctx.lineTo(lx,h*0.94);ctx.stroke();ctx.restore();}
  for(var si=0;si<STEPS.length;si++){var s=STEPS[si],sy=h*s.yp;if(s.sep){ctx.save();ctx.strokeStyle='rgba(255,255,255,0.28)';ctx.lineWidth=1;ctx.setLineDash([3,5]);ctx.beginPath();ctx.moveTo(bx1,sy);ctx.lineTo(bx2,sy);ctx.stroke();ctx.fillStyle='rgba(255,255,255,0.05)';rr(ctx,bx1,sy-8,s.label.length*6.2+14,16,3);ctx.fill();ctx.fillStyle=M;ctx.font='10px monospace';ctx.textAlign='left';ctx.textBaseline='middle';ctx.fillText(s.label,bx1+5,sy);ctx.restore();continue;}var e=eg(s.fr,s.to,w),x1=e.x1,x2=e.x2,d=e.d,clx=(x1+x2)/2;var state=ct<s.ts?'pre':ct>s.te?'done':'live',alpha=state==='pre'?0.10:state==='done'?0.55:1.0;ctx.save();ctx.globalAlpha=alpha;ctx.strokeStyle=s.col;ctx.lineWidth=1.5;ctx.setLineDash([]);ctx.beginPath();ctx.moveTo(x1,sy);ctx.lineTo(x2,sy);ctx.stroke();ctx.fillStyle=s.col;ctx.beginPath();ctx.moveTo(x2,sy);ctx.lineTo(x2-d*7,sy-4);ctx.lineTo(x2-d*7,sy+4);ctx.closePath();ctx.fill();ctx.fillStyle=TXT;ctx.font='bold 10px monospace';ctx.textAlign='center';ctx.textBaseline='bottom';ctx.fillText(s.label,clx,sy-4);if(s.note){ctx.fillStyle=M;ctx.font='9px monospace';ctx.fillText(s.note,clx,sy-16);}ctx.restore();if(state==='live'){var p=ease((ct-s.ts)/(s.te-s.ts));dPkt(ctx,x1+(x2-x1)*p,sy+14,s.label,s.col);}}
  for(var i=0;i<NODES.length;i++){var nd=NODES[i],px=gx(nd.id,w),na=(nd.id==='rf'&&!inF2)?0.18:1.0;ctx.save();ctx.globalAlpha=na;ctx.shadowColor=nd.col;ctx.shadowBlur=14;rr(ctx,px-NW/2,nodeY-NH/2,NW,NH,8);ctx.fillStyle=NF;ctx.fill();ctx.shadowBlur=0;ctx.strokeStyle=nd.col;ctx.lineWidth=1.8;ctx.stroke();ctx.fillStyle=nd.col;ctx.font='bold 11px Inter,system-ui,sans-serif';ctx.textAlign='center';ctx.textBaseline='middle';ctx.fillText(nd.label,px,nodeY);ctx.restore();}
}
var dim,t0;
function loop(){var t=(performance.now()-t0)/1000;draw(dim.ctx,dim.w,dim.h,t);requestAnimationFrame(loop);}
window.addEventListener('load',function(){dim=setup();t0=performance.now();loop();});
window.addEventListener('resize',function(){dim=setup();});
})()\x3c/script></body></html>`} />;

<Info>
  **Novo CNPJ (IN 2229/24)**

  A Judit já aceita o novo formato de **CNPJ alfanumérico** em conformidade com a [Instrução Normativa RFB nº 2229/2024](https://normasinternet2.receita.fazenda.gov.br/#/consulta/externa/141102).

  * **Zero esforço:** nenhuma alteração é necessária na sua integração.
  * **Ambiente de teste:** utilize o documento `A1B2C3D4/E5F6-68` para validar o fluxo e receber um processo fictício de resposta.
</Info>

A **Consulta por Dados Cadastrais** retorna informações de identificação de uma Pessoa Física ou Jurídica: nome/razão social, situação cadastral, endereços, contatos, sócios e relacionamentos. Toda a chamada é síncrona e pode ler do datalake da Judit (rápido e barato) ou direto da Receita Federal em tempo real (`on_demand: true`).

> 🤖 Endpoint: `POST https://lawsuits.production.judit.io/entities`. `search_type` aceita `cpf`, `cnpj` ou `name`. `response_type` é sempre `entity`. Para resposta em tempo real (Receita), envie `on_demand: true` no payload.

<EntityAnimation />

<EndpointBadges auth billing="billable" flow={null} />

## Quando usar

<CardGroup cols={2}>
  <Card title="Onboarding e KYC" icon="user-check">
    Valide nome, situação cadastral e endereço durante o cadastro do cliente sem fricção adicional.
  </Card>

  <Card title="Enriquecimento de base" icon="database">
    Atualize seu CRM/ERP com dados consolidados por CPF/CNPJ.
  </Card>

  <Card title="Anti-fraude" icon="user-secret">
    Confronte dados informados pelo usuário com a versão oficial em segundos.
  </Card>

  <Card title="Mapeamento de grupo econômico" icon="sitemap">
    Use a resposta para descobrir filiais e relacionamentos societários ligados a um CNPJ.
  </Card>
</CardGroup>

## Datalake vs. On-Demand (Receita Federal)

| Característica | Datalake (padrão)                          | On-Demand (`on_demand: true`)              |
| :------------- | :----------------------------------------- | :----------------------------------------- |
| **Latência**   | ms                                         | segundos                                   |
| **Fonte**      | Cache JUDIT                                | Receita Federal em tempo real              |
| **Atualidade** | Última coleta JUDIT                        | Estado atual da Receita                    |
| **Custo**      | Mais barato                                | Mais caro                                  |
| **Caso ideal** | Onboarding rápido, enriquecimento em massa | Compliance crítico, decisões de alto risco |

## Passo 1: Criar a Consulta (POST)

`POST https://lawsuits.production.judit.io/entities`

### Exemplos por tipo de documento

<CodeGroup>
  ```json Por CPF theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "999.999.999-99"
      }
  }
  ```

  ```json Por CNPJ theme={null}
  {
      "search": {
          "search_type": "cnpj",
          "search_key": "99.999.999/9999-99"
      }
  }
  ```

  ```json Por Nome theme={null}
  {
      "search": {
          "search_type": "name",
          "search_key": "Nome teste"
      }
  }
  ```

  ```json On-Demand (Receita Federal) theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "999.999.999-99",
          "on_demand": true
      }
  }
  ```

  ```json CNPJ com sócios não mascarados theme={null}
  {
      "search": {
          "search_type": "cnpj",
          "search_key": "99.999.999/9999-99",
          "reveal_partners_documents": true
      }
  }
  ```
</CodeGroup>

<Warning>
  Ao realizar consultas por **nome**, é possível que existam homônimos (pessoas ou empresas com o mesmo nome). Sempre que possível, prefira CPF ou CNPJ para garantir maior precisão.
</Warning>

### Parâmetros do Payload

| Parâmetro                          | Tipo    | Obrigatório | Descrição                                                  |
| :--------------------------------- | :------ | :---------- | :--------------------------------------------------------- |
| `search.search_type`               | string  | **Sim**     | `"cpf"`, `"cnpj"` ou `"name"`.                             |
| `search.search_key`                | string  | **Sim**     | Documento ou nome a buscar.                                |
| `search.response_type`             | string  | **Sim**     | Sempre `"entity"`.                                         |
| `search.on_demand`                 | boolean | Não         | Se `true`, força leitura em tempo real na Receita Federal. |
| `search.reveal_partners_documents` | boolean | Não         | (CNPJ) Retorna documentos não mascarados dos sócios.       |

### Exemplo de Requisição (POST)

<CodeGroup>
  ```bash cURL (CPF) theme={null}
  curl --location 'https://lawsuits.production.judit.io/entities' \
    --header 'api-key: '"$JUDIT_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
      "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99"
      }
    }'
  ```

  ```bash cURL (CNPJ on-demand) theme={null}
  curl --location 'https://lawsuits.production.judit.io/entities' \
    --header 'api-key: '"$JUDIT_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
      "search": {
        "search_type": "cnpj",
        "search_key": "99.999.999/9999-99",
        "on_demand": true
      }
    }'
  ```

  ```python Python theme={null}
  import os, requests

  resp = requests.post(
      "https://lawsuits.production.judit.io/entities",
      headers={
          "api-key": os.environ["JUDIT_API_KEY"],
          "Content-Type": "application/json",
      },
      json={
          "search": {
              "search_type": "cpf",
              "search_key": "999.999.999-99",,
          }
      },
      timeout=30,
  )
  resp.raise_for_status()
  print(resp.json())
  ```

  ```javascript Node.js theme={null}
  const res = await fetch("https://lawsuits.production.judit.io/entities", {
    method: "POST",
    headers: {
      "api-key": process.env.JUDIT_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      search: {
        search_type: "cpf",
        search_key: "999.999.999-99",
        response_type: "entity",
      },
    }),
  });
  console.log(await res.json());
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "io"
      "net/http"
      "os"
  )

  func main() {
      body, _ := json.Marshal(map[string]any{
          "search": map[string]string{
              "search_type":   "cpf",
              "search_key":    "999.999.999-99",,
          },
      })
      req, _ := http.NewRequest("POST",
          "https://lawsuits.production.judit.io/entities",
          bytes.NewReader(body))
      req.Header.Set("api-key", os.Getenv("JUDIT_API_KEY"))
      req.Header.Set("Content-Type", "application/json")
      res, _ := http.DefaultClient.Do(req)
      defer res.Body.Close()
      out, _ := io.ReadAll(res.Body)
      println(string(out))
  }
  ```
</CodeGroup>

## Passo 2: Ler a Resposta

A resposta vem no corpo do mesmo POST. Os campos principais:

| Campo                           | Tipo   | Descrição                                                                  |
| :------------------------------ | :----- | :------------------------------------------------------------------------- |
| `request_id`                    | string | Identificador único da consulta.                                           |
| `response_data`                 | array  | Lista de entidades encontradas (segue o [Schema Entity](/schemas/entity)). |
| `response_data[].entity_type`   | string | `"person"` (PF) ou `"company"` (PJ).                                       |
| `response_data[].main_document` | string | CPF ou CNPJ.                                                               |
| `response_data[].addresses`     | array  | Endereços associados.                                                      |
| `response_data[].contacts`      | array  | Telefones e e-mails.                                                       |
| `response_data[].partners`      | array  | (PJ) Sócios e administradores.                                             |

### Exemplos de Resposta

<CodeGroup>
  ```json Resposta por CPF theme={null}
  {
      "has_lawsuits": false,
      "request_id": "5c618521-2ecc-4176-a573-431d2e0edeb2",
      "response_data": [
          {
              "entity_id": "",
              "entity_type": "person",
              "main_document": "999.999.999-99",
              "name": "JOÃO TESTE",
              "addresses": [
                  {
                      "street": "RUA RAMOS DE CARVALHO",
                      "number": "999",
                      "neighborhood": "CENTRO",
                      "city": "RIO DE JANEIRO",
                      "state": "RJ",
                      "country": "Brasil",
                      "zip_code": "99999999"
                  }
              ],
              "contacts": [
                  { "description": "21999999999", "contact_type": "phone" }
              ],
              "parents": [
                  { "name": "JANAINA DA SILVA", "kinship": "mother" }
              ],
              "tags": { "revenue_update_date": "2022-05-30T00:00:00.000Z" },
              "nationality": "BRASILEIRA",
              "birth_date": "1981-08-07T00:00:00.000Z",
              "gender": "male",
              "revenue_service_active": true,
              "created_at": "2024-10-12T13:28:59.051Z",
              "updated_at": "2024-10-12T13:28:59.051Z"
          }
      ]
  }
  ```

  ```json Resposta por CNPJ theme={null}
  {
      "has_lawsuits": false,
      "request_id": "6e5a24f7-f874-4234-8acc-419142e2b066",
      "response_data": [
          {
              "entity_id": "",
              "entity_type": "company",
              "main_document": "99.999.999/0009-99",
              "name": "FINGI - EM RECUPERACAO JUDICIAL",
              "social_name": "FING",
              "addresses": [
                  {
                      "street": "RUA DO JOÃO CIRILO",
                      "number": "99",
                      "complement": "ANDAR 9",
                      "neighborhood": "CENTRO",
                      "city": "RIO DE JANEIRO",
                      "state": "RJ",
                      "country": "BRASIL",
                      "zip_code": "99999999"
                  }
              ],
              "contacts": [
                  { "description": "999999999", "contact_type": "phone" },
                  { "description": "ouvidoria@fing.com.br", "contact_type": "email" }
              ],
              "partners": [
                  {
                      "entity_type": "company",
                      "main_document": "***999999**",
                      "name": "JOÃO DE OLIVEIRA SOUZA",
                      "position": "CONSELHEIRO DE ADMINISTRAÇÃO",
                      "tags": {
                          "age_group": "Entre 61 a 70 anos",
                          "start_date": "2018-09-25T00:00:00.000Z"
                      }
                  }
              ],
              "branch_activities": [
                  {
                      "code": "9999999",
                      "name": "SERVIÇOS DE ATENDIMENTO AO CLIENTE - SAC",
                      "active": true,
                      "main_activity": true
                  }
              ],
              "tags": { "revenue_update_date": "2005-11-03T00:00:00.000Z" },
              "nationality": "BRASILEIRA",
              "birth_date": "1966-09-26T00:00:00.000Z",
              "size": "DEMAIS",
              "legal_nature": {
                  "code": "2046",
                  "name": "SOCIEDADE ANÔNIMA ABERTA",
                  "active": true
              },
              "head_office": true,
              "revenue_service_active": true,
              "special_status": "RECUPERACAO JUDICIAL",
              "special_status_date": "2016-06-29T00:00:00.000Z",
              "share_capital": 99999999999
          }
      ]
  }
  ```

  ```json Resposta por Nome theme={null}
  {
      "request_id": "223458ec-f3a1-4851-8d2b-19672066565c",
      "response_data": [
          {
              "entity_id": "999.999.999-99",
              "entity_type": "person",
              "main_document": "999.999.999-99",
              "name": "Usuário Teste",
              "parents": [
                  { "name": "Usuário teste 1", "kinship": "mother" }
              ],
              "tags": {},
              "nationality": "BRASILEIRA",
              "birth_date": "1989-12-25T00:00:00.000Z",
              "gender": "male",
              "created_at": "2025-04-19T00:14:56.561Z",
              "updated_at": "2025-04-19T00:14:56.561Z"
          }
      ]
  }
  ```
</CodeGroup>

> Estrutura completa de cada item: veja [Schema Entity](/schemas/entity). Glossário de campos: [Glossário](/resource/glossary).

<Note>
  Ao consultar por CNPJ com `reveal_partners_documents: true`, retornamos os CPFs/CNPJs dos sócios sem mascaramento. Use somente quando há base legal/contratual (LGPD).
</Note>

## Erros comuns

| HTTP  | Quando acontece                                          | Como tratar |
| :---- | :------------------------------------------------------- | :---------- |
| `400` | Documento em formato inválido / `response_type` ausente. | V           |
