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

# Historical Query by Document (CPF/CNPJ/OAB/Name)

> Retrieve the full lawsuit history linked to a CPF, CNPJ, OAB or Name through Judit API's asynchronous flow, with advanced filters, pagination and alphanumeric CNPJ support.

export const EndpointBadges = ({auth = true, billing = "billable", flow = "sync", attachments = false, requiresVault = false}) => <div style={{
  marginTop: "-8px",
  marginBottom: "16px"
}}>
    {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 DocumentAnimation = () => <iframe sandbox="allow-scripts" scrolling="no" style={{
  width: '100%',
  height: '600px',
  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',T='#E0A82E',D='#8B5CF6',FE='#60A5FA',AM='#F6AD55',RE='#ef4444',M='#7A8599';
var BG='#090c0d',TXT='#e5e7eb',NF='#111827',PT='#0a1020';
var TOTAL=30.0;
var XP={app:0.06,judit:0.25,dl:0.46,ext:0.68,court:0.88};
var NW=80,NH=42;
var FLOWS=[
  {id:'dl',title:'① Asynchronous — Datalake + External Sources',sub:'Datalake + indexed external sources — no direct access to courts',col:D,ts:1,te:11,act:['app','judit','dl','ext'],steps:[
    {fr:'app',to:'judit',label:'POST /requests',note:'{search_type, search_key}',col:A,ts:1.2,te:2.0,yp:0.28},
    {fr:'judit',to:'app',label:'200 {request_id}',note:'status: pending',col:AM,ts:2.5,te:3.3,yp:0.37},
    {fr:'judit',to:'dl',label:'datalake search',note:'indexed history',col:D,ts:3.8,te:4.6,yp:0.47},
    {fr:'judit',to:'ext',label:'ext. sources search',note:'external bases',col:FE,ts:3.8,te:4.6,yp:0.57},
    {fr:'dl',to:'judit',label:'cover + parties',note:'datalake history',col:D,ts:5.2,te:6.0,yp:0.67},
    {fr:'ext',to:'judit',label:'external data',note:'enrichment',col:FE,ts:5.2,te:6.0,yp:0.77},
    {fr:'judit',to:'app',label:'webhook / polling',note:'consolidated response_data',col:J,ts:6.5,te:7.3,yp:0.87}]},
  {id:'od',title:'② On-Demand — Maximum Completeness',sub:'Datalake + external sources + courts in real time',col:T,ts:14,te:28,act:['app','judit','dl','ext','court'],steps:[
    {fr:'app',to:'judit',label:'POST /requests',note:'{on_demand: true}',col:A,ts:14.2,te:15.0,yp:0.28},
    {fr:'judit',to:'app',label:'200 {request_id}',note:'status: pending',col:AM,ts:15.5,te:16.3,yp:0.36},
    {fr:'judit',to:'dl',label:'datalake search',note:'indexed history',col:D,ts:16.8,te:17.6,yp:0.44},
    {fr:'judit',to:'ext',label:'ext. sources search',note:'external bases',col:FE,ts:16.8,te:17.6,yp:0.52},
    {fr:'dl',to:'judit',label:'cover + parties',note:'datalake history',col:D,ts:18.2,te:19.0,yp:0.60},
    {fr:'ext',to:'judit',label:'external data',note:'enrichment',col:FE,ts:18.2,te:19.0,yp:0.68},
    {fr:'judit',to:'court',label:'court extraction',note:'real-time data',col:T,ts:19.6,te:20.4,yp:0.76},
    {fr:'court',to:'judit',label:'court data',note:'maximum completeness',col:J,ts:20.9,te:21.7,yp:0.84},
    {fr:'judit',to:'app',label:'webhook / polling',note:'consolidated response_data',col:J,ts:22.2,te:23.0,yp:0.92}]}
];
var NODES=[
  {id:'app',label:'Your App',col:A},
  {id:'judit',label:'Judit API',col:J},
  {id:'dl',label:'Datalake',col:D},
  {id:'ext',label:'Ext. Sources',col:FE},
  {id:'court',label:'Courts',col:T}
];
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:n==='dl'?w*XP.dl:n==='ext'?w*XP.ext:w*XP.court;}
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;
  ctx.fillStyle=BG;ctx.fillRect(0,0,w,h);
  var fl=null;for(var i=0;i<FLOWS.length;i++){if(ct>=FLOWS[i].ts&&ct<FLOWS[i].te){fl=FLOWS[i];break;}}
  var nodeY=h*0.17;
  for(var i=0;i<NODES.length;i++){var n=NODES[i],lx=gx(n.id,w),ia=!fl||(fl.act.indexOf(n.id)>=0);ctx.save();ctx.strokeStyle=n.col;ctx.globalAlpha=ia?0.38:0.08;ctx.lineWidth=1;ctx.setLineDash([4,7]);ctx.beginPath();ctx.moveTo(lx,nodeY+NH/2);ctx.lineTo(lx,h*0.93);ctx.stroke();ctx.restore();}
  if(fl){ctx.save();ctx.fillStyle=fl.col;ctx.font='bold 13px Inter,system-ui,sans-serif';ctx.textAlign='center';ctx.textBaseline='middle';ctx.fillText(fl.title,w/2,h*0.055);ctx.fillStyle=M;ctx.font='10.5px Inter,system-ui,sans-serif';ctx.fillText(fl.sub,w/2,h*0.118);ctx.restore();}
  if(fl){for(var si=0;si<fl.steps.length;si++){var s=fl.steps[si],sy=h*s.yp,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),ia=!fl||(fl.act.indexOf(nd.id)>=0),isCx=fl&&(fl.id==='dl'&&nd.id==='court');ctx.save();ctx.globalAlpha=ia?1:0.18;if(ia){ctx.shadowColor=nd.col;ctx.shadowBlur=15;}rr(ctx,px-NW/2,nodeY-NH/2,NW,NH,8);ctx.fillStyle=NF;ctx.fill();ctx.shadowBlur=0;ctx.strokeStyle=isCx?RE:ia?nd.col:'rgba(255,255,255,0.10)';ctx.lineWidth=ia?1.8:1;ctx.stroke();ctx.fillStyle=isCx?RE:ia?nd.col:M;ctx.font='bold 11px Inter,system-ui,sans-serif';ctx.textAlign='center';ctx.textBaseline='middle';ctx.fillText(nd.label,px,nodeY);ctx.restore();if(isCx){ctx.save();ctx.strokeStyle=RE;ctx.lineWidth=2;ctx.globalAlpha=0.85;var bx=px+NW/2-12,by=nodeY-NH/2+10,br=8;ctx.beginPath();ctx.moveTo(bx-br,by-br);ctx.lineTo(bx+br,by+br);ctx.stroke();ctx.beginPath();ctx.moveTo(bx+br,by-br);ctx.lineTo(bx-br,by+br);ctx.stroke();ctx.restore();}}
  for(var f=0;f<FLOWS.length;f++){var ia=fl&&fl.id===FLOWS[f].id;ctx.save();ctx.beginPath();ctx.arc(w/2+(f-0.5)*24,h*0.962,ia?5:3,0,Math.PI*2);ctx.fillStyle=ia?FLOWS[f].col:'rgba(255,255,255,0.18)';ctx.fill();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();});
cv.addEventListener('click',function(e){var r=cv.getBoundingClientRect(),cx=e.clientX-r.left,cy=e.clientY-r.top;for(var f=0;f<FLOWS.length;f++){var dx=cx-(dim.w/2+(f-(FLOWS.length-1)/2)*24),dy=cy-dim.h*0.962;if(dx*dx+dy*dy<=144){t0=performance.now()-FLOWS[f].ts*1000;break;}}});
cv.addEventListener('mousemove',function(e){var r=cv.getBoundingClientRect(),cx=e.clientX-r.left,cy=e.clientY-r.top,over=false;for(var f=0;f<FLOWS.length;f++){var dx=cx-(dim.w/2+(f-(FLOWS.length-1)/2)*24),dy=cy-dim.h*0.962;if(dx*dx+dy*dy<=144){over=true;break;}}cv.style.cursor=over?'pointer':'default';});
})()\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>

<Info>
  **Cached response (`cached_response`)**

  When you create a lawsuit or historical query, Judit first checks whether the data already exists in our database. If it does, we return the result immediately — both in the API response and via webhook (if registered) — with the field `cached_response: true`.

  In parallel, Judit triggers a fresh fetch against the courts. If anything has changed, you receive **a second response** with `cached_response: false`. That is the most up-to-date result.

  This is why it is normal to receive two seemingly identical webhooks for the same `request_id`:

  * The first one comes from cache (`cached_response: true`)
  * The last one is the updated result (`cached_response: false`)

  Use this field to reliably identify which response represents the most recent state of the lawsuit.
</Info>

The **Historical Query by Document** returns **the entire lawsuit caseload** linked to a CPF, CNPJ, OAB or Name. It is the path of choice for due diligence, KYC, judicial-exposure mapping and any scenario where you need to know *which lawsuits exist* (cover + parties), without necessarily diving into each one.

> This page documents exclusively the **Asynchronous** flow of the Historical Query. The client must make a `POST /requests`, wait for processing (`GET /requests/{id}`), and retrieve the data at `GET /responses`. The Historical Query response returns a paginated array containing exclusively the Header and the Parties of the lawsuit (omitting case updates, attachments, phase, and status). You can filter the results either in the payload of the initial POST or in the *query strings* of the final GET.

<EndpointBadges auth billing="billable" flow="async" requiresVault />

## When to use

<CardGroup cols={2}>
  <Card title="Due diligence / KYC" icon="user-shield">
    Before signing a contract, discover the counterpart's full judicial exposure by CPF/CNPJ.
  </Card>

  <Card title="Credit and collections" icon="dollar-sign">
    Combine with filters (`amount_gte`, `side: "Passive"`) to prioritize outreach by claim amount.
  </Card>

  <Card title="Caseload watch" icon="briefcase">
    Cross-reference with [Tracking by document](/en/tracking/tracking-document) to detect **new lawsuits** after the initial query.
  </Card>

  <Card title="Lawyer intelligence (OAB)" icon="user-tie">
    Query by OAB to list every lawsuit a lawyer is involved in.
  </Card>
</CardGroup>

## Synchronous vs. Asynchronous

Before integrating, it is essential to understand the architectural difference that Judit offers for this endpoint:

* **Synchronous Query (Datalake Hotstorage):** The response with all lawsuits is returned instantly in the `body` of the `POST` itself. It does not require a status check. Ideal for flows sensitive to response latency, such as onboarding. *[See the Synchronous documentation here](/en/cache-judit/hotstorage).*
* **Asynchronous Query (Datalake / On-Demand):** This is the flow we will cover on this page. It searches multiple external sources or directly in the courts (On-Demand) in real time. It requires a 3-step flow (Create -> Check -> Consume).

***

<DocumentAnimation />

## Step 1: Create the Search Request (POST)

To initiate the asynchronous flow, make a `POST` request providing the desired document.

`POST https://requests.production.judit.io/requests`

### Historical query examples

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

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

  ```json Query by OAB theme={null}
  {
      "search": {
          "search_type": "oab",
          "search_key": "99999RJ"
      }
  }
  ```

  ```json Query by Name theme={null}
  {
      "search": {
          "search_type": "name",
          "search_key": "João Silva"
      }
  }
  ```
</CodeGroup>

<Warning>
  When performing queries by name, namesakes may exist (people or companies with the same name). We recommend that, whenever possible, you use unique identifiers, such as CPF or CNPJ, to ensure greater accuracy in the results.
</Warning>

### Base Payload Parameters

| Parameter            | Type    | Required | Description                                                                                                                                                |
| :------------------- | :------ | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search.search_type` | string  | **Yes**  | type of entity to be searched: `"cpf"`, `"cnpj"`, `"oab"`, or `"name"`.                                                                                    |
| `search.search_key`  | string  | **Yes**  | The value to be searched (e.g., `"999.999.999-99"`, `João Silva`).                                                                                         |
| `search.on_demand`   | boolean | No       | If `true`, forces the search in real time at the courts instead of the Datalake.                                                                           |
| `cache_ttl_in_days`  | integer | No       | Considers the cache valid if the last extraction occurred within the last X days.                                                                          |
| `customer_key`       | string  | No       | User key in the Credentials Vault (used to access the courts with credentials registered in the [credentials vault](/en/essentials/cofre-de-credenciais)). |

<Note>
  **About the use of `customer_key`:** This credential will only take effect if the `on_demand` parameter is set to `true`. When provided, Judit will access the courts in an authenticated manner, allowing the capture of **lawsuits under judicial secrecy** to which the credential owner (lawyer) is previously linked within the respective lawsuit.
</Note>

<CodeGroup>
  ```json asynchronous request theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "999.999.999-99",
          "cache_ttl_in_days": 7
      }
  }
  ```

  ```json on-demand request theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "999.999.999-99",
          "on_demand": true
      }
  }
  ```

  ```json on-demand request with customer_key theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "999.999.999-99",
          "on_demand": true,
          "customer_key": "ADV01"
      }
  }
  ```
</CodeGroup>

### Prior Request Filters (`search_params.filter`)

You can restrict the initial search by sending the `filter` object inside `search_params` in the body of your POST. This is highly recommended, as it prevents the bot from spending time processing courts or states or years that are not relevant to your business.

Below, we detail how to build each filter step by step.

#### 1. Pole and Case Value Filters

Allows you to search for lawsuits in which the person has sued someone, has been sued, or filter by amounts in reais.

* `side` (string): Which side of the lawsuit is the searched document on?
  * `"Active"` (Plaintiff)
  * `"Passive"` (Defendant)
  * `"Interested"` (Third-party interested)
  * `"Unknown"` (Pole not identified)
* `amount_gte` (number): Case value **Greater than or Equal to** (GTE = *Greater Than or Equal*).
* `amount_lte` (number): Case value **Less than or Equal to** (LTE = *Less Than or Equal*).

<CodeGroup>
  ```json theme={null}
  // I want to find lawsuits where the client is the Defendant ("Passive") 
  // AND the case value is between R$ 10,000 and R$ 50,000
  {
      "search": {
          "search_type": "cpf",
          "search_key": "999.999.999-99",
          "search_params": {
              "filter": {
                  "side": "Passive",
                  "amount_gte": 10000.00,
                  "amount_lte": 50000.00
              }
          }
      }
  }

  ```
</CodeGroup>

#### 2. Court Filters (Include and Exclude Rule)

To filter by specific states or courts, we use the `tribunals` object. It requires two pieces of information: the list of acronyms (`keys`) and a negation rule (`not_equal`).

## List of Accepted Courts (Filters)

Use the exact acronyms from the **Acronym (Key)** column below when filtering by courts (e.g., in the `tribunals.keys` parameter).

<AccordionGroup>
  <Accordion title="Superior Courts and Councils">
    | Acronym (Key) | Official Name of the Body                |
    | :------------ | :--------------------------------------- |
    | `STF`         | SUPREMO TRIBUNAL FEDERAL                 |
    | `STJ`         | SUPERIOR TRIBUNAL DE JUSTIÇA             |
    | `TST`         | TRIBUNAL SUPERIOR DO TRABALHO            |
    | `TSE`         | TRIBUNAL SUPERIOR ELEITORAL              |
    | `STM`         | SUPERIOR TRIBUNAL MILITAR                |
    | `CNJ`         | CONSELHO NACIONAL DE JUSTIÇA             |
    | `CJF`         | CONSELHO DA JUSTIÇA FEDERAL              |
    | `CSJT`        | CONSELHO SUPERIOR DA JUSTIÇA DO TRABALHO |
  </Accordion>

  <Accordion title="Federal Justice (TRF)">
    | Acronym (Key) | Official Name of the Body              |
    | :------------ | :------------------------------------- |
    | `TRF1`        | TRIBUNAL REGIONAL FEDERAL DA 1ª REGIÃO |
    | `TRF2`        | TRIBUNAL REGIONAL FEDERAL DA 2ª REGIÃO |
    | `TRF3`        | TRIBUNAL REGIONAL FEDERAL DA 3ª REGIÃO |
    | `TRF4`        | TRIBUNAL REGIONAL FEDERAL DA 4ª REGIÃO |
    | `TRF5`        | TRIBUNAL REGIONAL FEDERAL DA 5ª REGIÃO |
  </Accordion>

  <Accordion title="Labor Justice (TRT)">
    | Acronym (Key) | Official Name of the Body         |
    | :------------ | :-------------------------------- |
    | `TRT1`        | TRT DA 1ª REGIÃO (RJ)             |
    | `TRT2`        | TRT DA 2ª REGIÃO (SP - Capital)   |
    | `TRT3`        | TRT DA 3ª REGIÃO (MG)             |
    | `TRT4`        | TRT DA 4ª REGIÃO (RS)             |
    | `TRT5`        | TRT DA 5ª REGIÃO (BA)             |
    | `TRT6`        | TRT DA 6ª REGIÃO (PE)             |
    | `TRT7`        | TRT DA 7ª REGIÃO (CE)             |
    | `TRT8`        | TRT DA 8ª REGIÃO (PA/AP)          |
    | `TRT9`        | TRT DA 9ª REGIÃO (PR)             |
    | `TRT10`       | TRT DA 10ª REGIÃO (DF/TO)         |
    | `TRT11`       | TRT DA 11ª REGIÃO (AM/RR)         |
    | `TRT12`       | TRT DA 12ª REGIÃO (SC)            |
    | `TRT13`       | TRT DA 13ª REGIÃO (PB)            |
    | `TRT14`       | TRT DA 14ª REGIÃO (RO/AC)         |
    | `TRT15`       | TRT DA 15ª REGIÃO (SP - Campinas) |
    | `TRT16`       | TRT DA 16ª REGIÃO (MA)            |
    | `TRT17`       | TRT DA 17ª REGIÃO (ES)            |
    | `TRT18`       | TRT DA 18ª REGIÃO (GO)            |
    | `TRT19`       | TRT DA 19ª REGIÃO (AL)            |
    | `TRT20`       | TRT DA 20ª REGIÃO (SE)            |
    | `TRT21`       | TRT DA 21ª REGIÃO (RN)            |
    | `TRT22`       | TRT DA 22ª REGIÃO (PI)            |
    | `TRT23`       | TRT DA 23ª REGIÃO (MT)            |
    | `TRT24`       | TRT DA 24ª REGIÃO (MS)            |
  </Accordion>

  <Accordion title="State Justice (TJ)">
    | Acronym (Key) | Official Name of the Body                             |
    | :------------ | :---------------------------------------------------- |
    | `TJAC`        | TRIBUNAL DE JUSTIÇA DO ACRE                           |
    | `TJAL`        | TRIBUNAL DE JUSTIÇA DO ALAGOAS                        |
    | `TJAP`        | TRIBUNAL DE JUSTIÇA DO AMAPÁ                          |
    | `TJAM`        | TRIBUNAL DE JUSTIÇA DO AMAZONAS                       |
    | `TJBA`        | TRIBUNAL DE JUSTIÇA DA BAHIA                          |
    | `TJCE`        | TRIBUNAL DE JUSTIÇA DO CEARÁ                          |
    | `TJDF`        | TRIBUNAL DE JUSTIÇA DO DISTRITO FEDERAL E TERRITÓRIOS |
    | `TJES`        | TRIBUNAL DE JUSTIÇA DO ESPÍRITO SANTO                 |
    | `TJGO`        | TRIBUNAL DE JUSTIÇA DE GOIÁS                          |
    | `TJMA`        | TRIBUNAL DE JUSTIÇA DO MARANHÃO                       |
    | `TJMT`        | TRIBUNAL DE JUSTIÇA DO MATO GROSSO                    |
    | `TJMS`        | TRIBUNAL DE JUSTIÇA DO MATO GROSSO DO SUL             |
    | `TJMG`        | TRIBUNAL DE JUSTIÇA DE MINAS GERAIS                   |
    | `TJPA`        | TRIBUNAL DE JUSTIÇA DO PARÁ                           |
    | `TJPB`        | TRIBUNAL DE JUSTIÇA DA PARAÍBA                        |
    | `TJPR`        | TRIBUNAL DE JUSTIÇA DO PARANÁ                         |
    | `TJPE`        | TRIBUNAL DE JUSTIÇA DE PERNAMBUCO                     |
    | `TJPI`        | TRIBUNAL DE JUSTIÇA DO PIAUÍ                          |
    | `TJRJ`        | TRIBUNAL DE JUSTIÇA DO RIO DE JANEIRO                 |
    | `TJSP`        | TRIBUNAL DE JUSTIÇA DE SÃO PAULO                      |
    | `TJRN`        | TRIBUNAL DE JUSTIÇA DO RIO GRANDE DO NORTE            |
    | `TJRS`        | TRIBUNAL DE JUSTIÇA DO RIO GRANDE DO SUL              |
    | `TJRO`        | TRIBUNAL DE JUSTIÇA DE RONDÔNIA                       |
    | `TJRR`        | TRIBUNAL DE JUSTIÇA DE RORAIMA                        |
    | `TJSC`        | TRIBUNAL DE JUSTIÇA DE SANTA CATARINA                 |
    | `TJSE`        | TRIBUNAL DE JUSTIÇA DE SERGIPE                        |
  </Accordion>

  <Accordion title="Electoral Justice (TRE)">
    | Acronym (Key) | Official Name of the Body                          |
    | :------------ | :------------------------------------------------- |
    | `TRE-AC`      | TRIBUNAL REGIONAL ELEITORAL DO ACRE                |
    | `TRE-AL`      | TRIBUNAL REGIONAL ELEITORAL DO ALAGOAS             |
    | `TRE-AP`      | TRIBUNAL REGIONAL ELEITORAL DO AMAPÁ               |
    | `TRE-AM`      | TRIBUNAL REGIONAL ELEITORAL DO AMAZONAS            |
    | `TRE-BA`      | TRIBUNAL REGIONAL ELEITORAL DA BAHIA               |
    | `TRE-CE`      | TRIBUNAL REGIONAL ELEITORAL DO CEARÁ               |
    | `TRE-DF`      | TRIBUNAL REGIONAL ELEITORAL DO DISTRITO FEDERAL    |
    | `TRE-ES`      | TRIBUNAL REGIONAL ELEITORAL DO ESPÍRITO SANTO      |
    | `TRE-GO`      | TRIBUNAL REGIONAL ELEITORAL DE GOIÁS               |
    | `TRE-MA`      | TRIBUNAL REGIONAL ELEITORAL DO MARANHÃO            |
    | `TRE-MT`      | TRIBUNAL REGIONAL ELEITORAL DO MATO GROSSO         |
    | `TRE-MS`      | TRIBUNAL REGIONAL ELEITORAL DO MATO GROSSO DO SUL  |
    | `TRE-MG`      | TRIBUNAL REGIONAL ELEITORAL DE MINAS GERAIS        |
    | `TRE-PA`      | TRIBUNAL REGIONAL ELEITORAL DO PARÁ                |
    | `TRE-PB`      | TRIBUNAL REGIONAL ELEITORAL DA PARAÍBA             |
    | `TRE-PR`      | TRIBUNAL REGIONAL ELEITORAL DO PARANÁ              |
    | `TRE-PE`      | TRIBUNAL REGIONAL ELEITORAL DE PERNAMBUCO          |
    | `TRE-PI`      | TRIBUNAL REGIONAL ELEITORAL DO PIAUÍ               |
    | `TRE-RJ`      | TRIBUNAL REGIONAL ELEITORAL DO RIO DE JANEIRO      |
    | `TRE-RN`      | TRIBUNAL REGIONAL ELEITORAL DO RIO GRANDE DO NORTE |
    | `TRE-RS`      | TRIBUNAL REGIONAL ELEITORAL DO RIO GRANDE DO SUL   |
    | `TRE-RO`      | TRIBUNAL REGIONAL ELEITORAL DE RONDÔNIA            |
    | `TRE-RR`      | TRIBUNAL REGIONAL ELEITORAL DE RORAIMA             |
    | `TRE-SC`      | TRIBUNAL REGIONAL ELEITORAL DE SANTA CATARINA      |
    | `TRE-SE`      | TRIBUNAL REGIONAL ELEITORAL DE SERGIPE             |
    | `TRE-SP`      | TRIBUNAL REGIONAL ELEITORAL DE SÃO PAULO           |
    | `TRE-TO`      | TRIBUNAL REGIONAL ELEITORAL DO TOCANTINS           |
  </Accordion>

  <Accordion title="Military Justice (Federal and State)">
    | Acronym (Key) | Official Name of the Body                                  |
    | :------------ | :--------------------------------------------------------- |
    | `CJM1`        | PRIMEIRA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                  |
    | `CJM2`        | SEGUNDA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                   |
    | `CJM3`        | TERCEIRA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                  |
    | `CJM4`        | QUARTA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                    |
    | `CJM5`        | QUINTA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                    |
    | `CJM6`        | SEXTA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                     |
    | `CJM7`        | SÉTIMA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                    |
    | `CJM8`        | OITAVA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                    |
    | `CJM9`        | NONA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                      |
    | `CJM10`       | DÉCIMA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                    |
    | `CJM11`       | DÉCIMA PRIMEIRA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR           |
    | `CJM12`       | DÉCIMA SEGUNDA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR            |
    | `TJM-MG`      | TRIBUNAL DE JUSTIÇA MILITAR DO ESTADO DE MINAS GERAIS      |
    | `TJM-RS`      | TRIBUNAL DE JUSTIÇA MILITAR DO ESTADO DO RIO GRANDE DO SUL |
    | `TJM-SP`      | TRIBUNAL DE JUSTIÇA MILITAR DO ESTADO DE SÃO PAULO         |
  </Accordion>
</AccordionGroup>

* **Inclusion:** If `not_equal` is `false`, the API will search **ONLY** in the courts from the list.
* **Exclusion:** If `not_equal` is `true`, the API will search throughout Brazil, **EXCEPT** in the courts from the list.

<Accordion title="JSON Example: Including vs. Excluding Courts" defaultOpen>
  <CodeGroup>
    ```json Search ONLY in these theme={null}
    // Returns only lawsuits from São Paulo and Bahia
    {
        "search": {
            "search_type": "cpf",
            "search_key": "999.999.999-99",
            "search_params": {
                "filter": {
                    "tribunals": {
                        "keys": [
                            "TJSP",
                            "TJBA"
                        ],
                        "not_equal": false
                    }
                }
            }
        }
    }

    ```

    ```json Search in ALL, EXCEPT these theme={null}
    // Returns from all over Brazil, but ignores Federal Justice (TRFs)
    {
        "search": {
            "search_type": "cpf",
            "search_key": "999.999.999-99",
            "search_params": {
                "filter": {
                    "tribunals": {
                        "keys": [
                            "TRF1",
                            "TRF2",
                            "TRF3",
                            "TRF4",
                            "TRF5",
                            "TRF6"
                        ],
                        "not_equal": true
                    }
                }
            }
        }
    }

    ```
  </CodeGroup>
</Accordion>

#### 3. Subject and Class Filters (CNJ Standard)

The Judit API uses the official **Unified Procedural Tables (TPU)** from the National Council of Justice (CNJ). You can filter lawsuits by entering the exact numeric codes from these tables.

👉 *To find out the official codes for Classes and Subjects, visit the [Public Query of SGT/CNJ](https://www.cnj.jus.br/sgt/consulta_publica_classes.php).*

The filter mechanics work as follows:

* **Subjects (`subject_codes`):** Uses the lists `contains` (I want lawsuits that contain these codes) and `not_contains` (I do not want lawsuits that contain these codes).
* **Classes (`classification_codes`):** Uses the `keys` list and the `not_equal` rule (the same inclusion/exclusion logic as courts).

<Accordion title="JSON Example: Filtering by Subjects and Classes">
  ```json theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "99999999999",
          "search_params": {
              "filter": {
                  // I want lawsuits that have subject 10433, but I reject them if they have 1120
                  "subject_codes": {
                      "contains": [
                          "10433"
                      ],
                      "not_contains": [
                          "1120"
                      ]
                  },
                  // I want EXACTLY procedural class 985 (e.g., Labor Action)
                  "classification_codes": {
                      "keys": [
                          "985"
                      ],
                      "not_equal": false
                  }
              }
          }
      }
  }
  ```
</Accordion>

#### 4. Date and Deadline Filters

Optimize the search by time slices using the universal date format (ISO 8601: `YYYY-MM-DDTHH:mm:ss.sssZ`).

* `distribution_date_gte` (string): Returns lawsuits filed (initiated) **on or after** a date.
* `last_step_date_gte` (string): Returns lawsuits whose **last case update** occurred **on or after** a date.
* `last_step_date_lte` (string): Returns lawsuits whose **last case update** occurred **before** a date.

<Accordion title="JSON Example: Filtering by Dates">
  ```json theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "99999999999",
          "search_params": {
              // I want lawsuits that had any case update on or after October 10, 2024
              "filter": {
                  "last_step_date_gte": "2024-10-10T00:00:00.000Z"
              }
          }
      }
  }
  ```
</Accordion>

#### 5. Restrictive Filters for Other Parties

Want to know if João sued Company X? You can use the Names and Documents filters of other parties involved in the lawsuit.

* `party_names` (array of strings): List of exact names that must appear in the lawsuit.
* `party_documents` (array of strings): List of CPFs/CNPJs that must appear in the lawsuit.

<Info>
  **Note when using together with the `side` filter:** If you use the `party_names` or `party_documents` filter together with the `side` filter, the "Pole" rule (Plaintiff/Defendant) will only be applied to the main document you are searching for, and **not** to the extra names/documents listed here.
</Info>

<Accordion title="JSON Example: Specific Parties">
  ```json theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "99999999999",
          "search_params": {
              // Searching by the main CPF (via search_key), but requiring that
              // "Empresa Exemplo" or the CNPJ "99.999.999/0001-99" also be present in the lawsuit.
              "filter": {
                  "party_names": [
                      "EMPRESA EXEMPLO LTDA"
                  ],
                  "party_documents": [
                      "99999999000199"
                  ]
              }
          }
      }
  }
  ```
</Accordion>

### Request Example (POST)

<CodeGroup>
  ```bash cURL (Step 1) theme={null}
  curl --location 'https://requests.production.judit.io/requests/' \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
      "search": {
          "search_type": "cpf",
          "search_key": "999.999.999-99",
          "on_demand": true,
          "search_params": {
              "filter": {
                  "side": "Passive",
                  "tribunals": {
                      "keys": ["TJBA"],
                      "not_equal": false
                  }
              }
          }
      }
  }'
  ```
</CodeGroup>

Save the `request_id` (e.g., `05ee9825...`) generated in the response of this call. It is your passport to the next steps.

***

<Info>
  **🚀 Shortcut: Automate with Webhooks (Recommended)**

  If you have a Webhook URL configured, **Steps 2 and 3 below are entirely optional**.
  Instead of programming your application to keep polling the request status, the Judit API will send the found lawsuits **incrementally** directly to your server as soon as they are captured, finishing the flow with a `request_completed` event.

  👉 *[Learn how to configure and receive Webhooks here](/en/webhook/callbacks)*
</Info>

***

## Step 2: Check the Request Status

Since a document can be linked to hundreds of lawsuits in Brazil, collection takes time. You must check the macro status of the request using the ID from Step 1.

`GET https://requests.production.judit.io/requests/<REQUEST_ID>`

```bash cURL (Step 2) theme={null}
curl --location 'https://requests.production.judit.io/requests/<request_id>' \
--header 'api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data ''
```

You must perform *polling* (periodic queries) on this route until the `"status"` property changes from `"pending"` to **`"completed"`**.
*(Note: Using Webhooks eliminates the need for this step).*

### Granular Verification (On-Demand Only)

Since the On-Demand search queries dozens of systems simultaneously, you can track the individual status of each accessed court using the *Crawls* route:

```bash cURL theme={null}
curl --location 'https://crawler.production.judit.io/crawls/request/<request_id>?page=1&page_size=10' \
    --header 'api-key: <api-key>'
```

<Accordion title="See example of On-Demand Status Response">
  ```json theme={null}
  {
      "page": 1,
      "page_data": [
          {
              "source_name": "JPje - RO - Lawsuit - Auth - 2 instance",
              "tribunal_acronym": "TJRO",
              "status": "done",
              "updated_at": "2025-10-28T00:04:40.651Z"
          },
          {
              "source_name": "JTJRJ - RJ - Lawsuit - Auth - 1 instance",
              "tribunal_acronym": "TJRJ",
              "status": "pending",
              "updated_at": "2025-10-28T00:04:53.157Z"
          }
      ]
  }
  ```
</Accordion>

***

## Step 3: Consume and Filter the Results (GET)

As soon as the status in Step 2 returns `"completed"`, the data is ready!

This is where, on the `GET /responses` route, you pull the final JSON. The big advantage of this endpoint is that **it allows you to apply dynamic filters via URL (Query Params)**, allowing you to slice, order, and paginate the final response however you want, without having to generate a new request (POST).

`GET https://requests.production.judit.io/responses/`

### Dynamic URL Filters (Query Params)

These are the parameters you can concatenate to your final request:

| Query Param              | Type / Format | Description                                                                          |
| :----------------------- | :------------ | :----------------------------------------------------------------------------------- |
| `request_id`             | string (UUID) | **Required.** The ID generated in Step 1.                                            |
| `page`                   | integer       | Current page number for navigation (Default: `1`).                                   |
| `page_size`              | integer       | Number of results returned per page. **Maximum allowed: 1000** (Recommended: `100`). |
| `response_type`          | JSON array    | Desired response type. E.g., `["lawsuit"]`.                                          |
| `code`                   | JSON array    | Filters by specific lawsuit numbers. E.g., `["0601708-42..."]`.                      |
| `instance`               | JSON array    | Filters by jurisdiction degree. E.g., `[1, 2]`.                                      |
| `cached`                 | boolean       | Returns only cached lawsuits (`true`) or newly captured ones (`false`).              |
| `classifications_code`   | JSON array    | Exact procedural class codes (E.g., `["437"]`).                                      |
| `subjects_code`          | JSON array    | Exact CNJ subject codes (E.g., `["6226"]`).                                          |
| `created_at_gte` / `lte` | string (Date) | Filters by the date the lawsuit entered the Judit database.                          |
| `order`                  | JSON object   | Orders the listing. E.g., `{"created_at": "desc"}`.                                  |
| `tags.criminal`          | boolean       | Returns `true` only for lawsuits in the criminal sphere.                             |

<CodeGroup>
  ```bash cURL (Basic Search) theme={null}
  # Returns the lawsuits using only the required parameter
  curl -X GET "https://requests.production.judit.io/responses?request_id=<YOUR_REQUEST_ID>" \
    -H "api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```bash cURL (Advanced Search with Filters) theme={null}
  # The -g (--globoff) parameter allows the use of brackets [] in the URL without breaking the terminal.
  # Note: In your application, remember to apply URL Encoding to these parameters.

  curl -g -X GET "https://requests.production.judit.io/responses\
  ?request_id=<YOUR_REQUEST_ID>\
  &response_type=[\"lawsuit\"]\
  &code=[\"0601708-42.2025.8.04.4700\"]\
  &instance=[1,2]\
  &cached=false\
  &classifications_code=[\"437\"]\
  &classifications_name=[\"PROCEDIMENTO DO JUIZADO ESPECIAL CÍVEL\"]\
  &subjects_code=[\"6226\"]\
  &subjects_name=\"INCLUSÃO INDEVIDA EM CADASTRO DE INADIMPLENTES\"\
  &created_at_gte=2026-03-01T00:00:00.000Z\
  &created_at_lte=2026-03-05T00:00:00.000Z\
  &request_created_at_gte=2026-03-02T00:00:00.000Z\
  &request_created_at_lte=2026-03-05T00:00:00.000Z\
  &page=1\
  &page_size=1000\
  &order={\"created_at\":\"desc\"}\
  &tags.criminal=true" \
    -H "api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json"
  ```
</CodeGroup>

### The Response Format

The return provides the pagination keys and the `page_data` array, where each object contains the `response_data` (The Lawsuit Header).

<ParamField body="request_status" name="request_status" type="string">
  Final status of the response (Must be `completed`).
</ParamField>

<ParamField body="page" name="page" type="integer">
  Current page of the search.
</ParamField>

<ParamField body="page_count" name="page_count" type="integer">
  Total number of lawsuits rendered on this page.
</ParamField>

<ParamField body="all_count" name="all_count" type="integer">
  Absolute total of lawsuits found and linked to the document.
</ParamField>

<ParamField body="all_pages_count" name="all_pages_count" type="integer">
  Total number of available pages.
</ParamField>

<ParamField body="page_data" name="page_data" type="array">
  Array of objects. Each object contains the `response_data` key that holds the [Lawsuit Header](/en/schemas/lawsuit-object).
</ParamField>

<Accordion title="Ver Exemplo da Estrutura do Processo Retornado">
  ```json theme={null}
  {
    "page": 1,
    "page_count": 1,
    "all_count": 1,
    "all_pages_count": 1,
    "request_status": "completed",
    "page_data": [
      {
        "request_id": "05ee9825-b2b4-480b-b29e-f071ca7d9c72",
        "response_id": "e49d2e2c-92ed-4dad-8701-c53a569d675b",
        "response_type": "lawsuit",
        "response_data": {
          "code": "0000000-00.0000.0.00.0000",
          "tribunal_acronym": "TJSP",
          "instance": 1,
          "parties": [
            { "name": "Usuário teste", "side": "Active", "person_type": "Autor" }
          ]
        }
      }
    ]
  }
  ```
</Accordion>
