> ## 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.

# Registration Data by CPF, CNPJ or Name

> Get registration data (individual or legal entity) synchronously through the /entities endpoint of the Judit API. Supports datalake query or real-time call to the Brazilian Federal Revenue (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:'Your App',col:A},{id:'judit',label:'Judit API',col:J},{id:'rf',label:'Federal Revenue',col:R}];
var STEPS=[
  {sep:true,label:'Request 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:'Request 2 — On-Demand (Federal Revenue)',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:'query RF',note:'real-time',col:R,ts:5.1,te:5.9,yp:0.71},
  {fr:'rf',to:'judit',label:'up-to-date data',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('Registration Data Query',w/2,h*0.04);
  ctx.fillStyle=M;ctx.font='10px Inter,system-ui,sans-serif';ctx.fillText('Datalake or Federal Revenue in real time',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>
  **New CNPJ format (IN 2229/24)**

  Judit already accepts the new **alphanumeric CNPJ** format in compliance with the [Brazilian Federal Revenue Normative Instruction No. 2229/2024](https://normasinternet2.receita.fazenda.gov.br/#/consulta/externa/141102).

  * **Zero effort:** no changes are required in your integration.
  * **Test environment:** use the document `A1B2C3D4/E5F6-68` to validate the flow and receive a mock lawsuit in response.
</Info>

The **Registration Data Query** returns identity information for an individual or company: name/corporate name, registration status, addresses, contacts, partners and relationships. The whole call is synchronous and can read from Judit's datalake (fast and cheap) or directly from the Brazilian Federal Revenue in real time (`on_demand: true`).

> 🤖 Endpoint: `POST https://lawsuits.production.judit.io/entities`. `search_type` accepts `cpf`, `cnpj` or `name`. `response_type` is always `entity`. For real-time response (Receita Federal), send `on_demand: true` in the payload.

<EntityAnimation />

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

## When to use

<CardGroup cols={2}>
  <Card title="Onboarding and KYC" icon="user-check">
    Validate name, registration status and address during customer onboarding without extra friction.
  </Card>

  <Card title="Database enrichment" icon="database">
    Update CRM/ERP records with consolidated data by CPF/CNPJ.
  </Card>

  <Card title="Anti-fraud" icon="user-secret">
    Cross-check user-supplied data against the official source in seconds.
  </Card>

  <Card title="Corporate group mapping" icon="sitemap">
    Use the response to discover branches and corporate relationships linked to a CNPJ.
  </Card>
</CardGroup>

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

| Trait         | Datalake (default)               | On-Demand (`on_demand: true`)            |
| :------------ | :------------------------------- | :--------------------------------------- |
| **Latency**   | ms                               | seconds                                  |
| **Source**    | Judit cache                      | Brazilian Federal Revenue (live)         |
| **Freshness** | Last Judit collection            | Current Receita state                    |
| **Cost**      | Lower                            | Higher                                   |
| **Best for**  | Fast onboarding, mass enrichment | Critical compliance, high-risk decisions |

## Step 1: Create the query (POST)

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

### Examples by document type

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

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

  ```json By Name theme={null}
  {
      "search": {
          "search_type": "name",
          "search_key": "John Smith",
          "response_type": "entity"
      }
  }
  ```

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

  ```json CNPJ with unmasked partners theme={null}
  {
      "search": {
          "search_type": "cnpj",
          "search_key": "99.999.999/9999-99
          "reveal_partners_documents": true
      }
  }
  ```
</CodeGroup>

<Warning>
  For **name** queries, homonyms are possible. Whenever possible, prefer CPF or CNPJ for accuracy.
</Warning>

### Payload parameters

| Parameter                          | Type    | Required | Description                                                       |
| :--------------------------------- | :------ | :------- | :---------------------------------------------------------------- |
| `search.search_type`               | string  | **Yes**  | `"cpf"`, `"cnpj"` or `"name"`.                                    |
| `search.search_key`                | string  | **Yes**  | Document or name to search.                                       |
| `search.response_type`             | string  | **Yes**  | Always `"entity"`.                                                |
| `search.on_demand`                 | boolean | No       | If `true`, forces a live read from the Brazilian Federal Revenue. |
| `search.reveal_partners_documents` | boolean | No       | (CNPJ) Returns unmasked partner documents.                        |

### Request example (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",
        "response_type": "entity"
      }
    }'
  ```

  ```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
      }
    }'
  ```

  ```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());
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://lawsuits.production.judit.io/entities');
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'api-key: ' . getenv('JUDIT_API_KEY'),
          'Content-Type: application/json',
      ],
      CURLOPT_POSTFIELDS => json_encode([
          'search' => [
              'search_type'   => 'cpf',
              'search_key'    => '999.999.999-99',
              'response_type' => 'entity',
          ],
      ]),
  ]);
  $response = curl_exec($ch);
  echo $response;
  ```

  ```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())
  ```

  ```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>

## Step 2: Read the response

The response comes in the same POST body. Main fields:

| Field                           | Type   | Description                                                               |
| :------------------------------ | :----- | :------------------------------------------------------------------------ |
| `request_id`                    | string | Unique query identifier.                                                  |
| `response_data`                 | array  | List of found entities (follows the [Entity Schema](/en/schemas/entity)). |
| `response_data[].entity_type`   | string | `"person"` (PF) or `"company"` (PJ).                                      |
| `response_data[].main_document` | string | CPF or CNPJ.                                                              |
| `response_data[].addresses`     | array  | Associated addresses.                                                     |
| `response_data[].contacts`      | array  | Phones and emails.                                                        |
| `response_data[].partners`      | array  | (PJ) Partners and administrators.                                         |

### Response examples

<CodeGroup>
  ```json Response by 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 Response by CNPJ theme={null}
  {
      "has_lawsuits": false,
      "request_id": "6e5a24f7-f874-4234-8acc-419142e2b066",
      "response_data": [
          {
              "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",
                      "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": "BOARD MEMBER",
                      "tags": {
                          "age_group": "61-70",
                          "start_date": "2018-09-25T00:00:00.000Z"
                      }
                  }
              ],
              "branch_activities": [
                  {
                      "code": "9999999",
                      "name": "CUSTOMER SUPPORT - SAC",
                      "active": true,
                      "main_activity": true
                  }
              ],
              "tags": { "revenue_update_date": "2005-11-03T00:00:00.000Z" },
              "size": "OTHER",
              "legal_nature": {
                  "code": "2046",
                  "name": "PUBLIC CORPORATION",
                  "active": true
              },
              "head_office": true,
              "revenue_service_active": true,
              "special_status": "JUDICIAL RECOVERY",
              "special_status_date": "2016-06-29T00:00:00.000Z",
              "share_capital": 99999999999
          }
      ]
  }
  ```

  ```json Response by Name 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": "Test User",
              "parents": [
                  { "name": "Mother Name", "kinship": "mother" }
              ],
              "tags": {},
              "nationality": "BRASILEIRA",
              "birth_date": "1989-12-25T00:00:00.000Z",
              "gender": "male"
          }
      ]
  }
  ```
</CodeGroup>

> Full structure of each item: see [Entity Schema](/en/schemas/entity). Field glossary: [Glossary](/en/resource/glossary).

<Note>
  When querying by CNPJ with `reveal_partners_documents: true`, partner CPFs/CNPJs are returned without masking. Only use it when you have a clear legal basis (KYC, AML, due diligence) — and never persist the unmasked values longer than necessary.
</Note>
