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

# Synchronous Datalake Query (Hot Storage)

> Instantly query Judit's datalake (Hot Storage) by CPF, CNPJ, OAB or Name. Synchronous millisecond response with already-indexed data — ideal for real-time validations and flows.

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

<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 **Hot Storage Synchronous Query** returns, in milliseconds, every lawsuit in our datalake linked to a CPF, CNPJ, OAB, Name or CNJ. There is no queue or wait for the court: the response comes straight from Judit's cache.

> 🤖 Endpoint: `POST https://lawsuits.production.judit.io/lawsuits`. The response is synchronous (HTTP 200 with the full JSON). This route does not query the court — it reads Judit's datalake, so there may be a small lag versus the most current state of the lawsuit. If you need real-time data, use [`POST /requests`](/en/requests/requests) (async).

<EndpointBadges auth billing="billable" flow="sync" />

<Warning>
  **Searching by lawsuit number (CNJ)?**

  This route is recommended for discovery by **CPF, CNPJ, OAB or Name**. For queries by **lawsuit number (CNJ)**, the datalake data may be stale — or the lawsuit may not even exist in our base yet. Use the [On-Demand Query](/en/cache-judit/on-demand) to get a real-time freshness guarantee at the court without leaving the synchronous flow.
</Warning>

## Synchronous vs. asynchronous — which one?

| Trait | Synchronous (Hot Storage) | Asynchronous (Requests) |
| - | - | - |
| **Latency** | ms (immediate) | seconds to minutes |
| **Source** | Judit datalake (cache) | Live court |
| **Freshness** | Last Judit collection | Court state right now |
| **Webhook** | N/A | Yes, optional |
| **Cost** | Lower | Higher |
| **Best for** | Quick validation, dashboards, interactive search | Due diligence, forced refresh, on-demand fetch |

## When to use

<CardGroup cols={2}>
  <Card title="Real-time validation" icon="bolt">
    Onboarding, KYC, autocomplete — whenever you need an immediate response for the UI.
  </Card>

  <Card title="Interactive dashboards" icon="chart-line">
    Dashboards and BI listing lawsuits linked to a customer without forcing a court refresh.
  </Card>

  <Card title="Risk pre-filtering" icon="filter">
    Before firing an expensive async query, find out quickly whether it's worth it.
  </Card>

  <Card title="Counts and aggregates" icon="hashtag">
    Combine with [`/lawsuits/count`](/en/api-reference/endpoint/crawler/req-count) and [`/lawsuits/synthetic`](/en/cache-judit/cache-grouped) for analytics.
  </Card>
</CardGroup>

<Warning>
  All synchronous queries accept **filters** (court, claim amount, classes, parties, dates, phase). See the full list at [historical-query filters](/en/requests/request-document#payload-da-solicitação) — the same `search_params.filter` object applies here.
</Warning>

## Step 1: Create the synchronous query (POST)

To start the synchronous query, make a `POST` request with the desired document.

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

### Synchronous 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": "John Smith"
      }
  }
  ```
</CodeGroup>

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

### Payload parameters

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `search.search_type` | string | **Yes** | Entity type: `"cpf"`, `"cnpj"`, `"oab"` or `"name"`. |
| `search.search_key` | string | **Yes** | Value to search (e.g. `"999.999.999-99"`, `"John Smith"`). |
| `search.search_params.filter` | object | No | Structural filters (court, amount, classes, parties, dates). Same shape as the [historical query](/en/requests/request-document#filtros-prévios-da-requisição-search_params-filter). |
| `search.search_params.with_inferred_parties` | boolean | No | If `true`, also includes lawsuits in which the link to the searched document was inferred by Judit. Default: `false`. |

### Party inference (`search_params.with_inferred_parties`)

Many courts do not publish the parties' CPF/CNPJ — only their names. With `with_inferred_parties: true`, the query also considers lawsuits in which the link to the searched document was **inferred** through Judit's internal validations, instead of being read directly from the court. The parameter is opt-in: when omitted it defaults to `false`.

```json Query with party inference theme={null}
{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99",
        "search_params": {
            "with_inferred_parties": true
        }
    }
}
```

Every party in the response carries the `was_inferred` field: `false` when the document was published by the court itself and `true` when it was inferred by Judit (in that case the `documents` array usually comes empty and `main_document` is the result of the inference). Treat the absence of the field as `false` — the [historical query](/en/requests/request-document) has a response example with an inferred party.

<Warning>
  **Risk of homonyms.** Because the inference starts from the party's **name**, there is a chance of linking to the searched document a lawsuit that actually belongs to another person or company with an identical or very similar name. The internal validations reduce this risk, but do not eliminate it. In searches with `search_type: "name"`, this risk adds up to the homonyms of the searched term itself.

  Use `was_inferred` to decide how to treat each lawsuit: an inferred link does not carry the same reliability as a document published by the court.
</Warning>

### Most common filters (`search_params.filter`)

The synchronous query accepts the same filters as the historical query. Practical examples:

<CodeGroup>
  ```json Filter by court (TJRJ) theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "999.999.999-99",
          "search_params": {
              "filter": {
                  "tribunals": { "keys": ["TJRJ"], "not_equal": false }
              }
          }
      }
  }
  ```

  ```json Passive side + amount theme={null}
  {
      "search": {
          "search_type": "cnpj",
          "search_key": "00.000.000/0001-00",
          "search_params": {
              "filter": {
                  "side": "Passive",
                  "amount_gte": 50000
              }
          }
      }
  }
  ```

  ```json Distribution-date window theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "999.999.999-99",
          "search_params": {
              "filter": {
                  "distribution_date_gte": "2024-01-01T00:00:00.000Z",
                  "distribution_date_lte": "2024-12-31T23:59:59.000Z"
              }
          }
      }
  }
  ```

  ```json Exclude courts theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "999.999.999-99",
          "search_params": {
              "filter": {
                  "tribunals": { "keys": ["TJSP"], "not_equal": true }
              }
          }
      }
  }
  ```
</CodeGroup>

> Full list of accepted courts: see [Historical-query filters](/en/requests/request-document#lista-de-tribunais-aceitos-filtros).

### Request example (POST)

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

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

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

  ```javascript Node.js theme={null}
  const res = await fetch("https://lawsuits.production.judit.io/lawsuits", {
    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" },
    }),
  });
  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/lawsuits",
          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 body of the same POST** (no polling). Main fields:

| Field | Type | Description |
| :- | :- | :- |
| `has_lawsuits` | boolean | `true` when lawsuits were found in the datalake. |
| `request_id` | string | Unique query identifier — useful for auditing. |
| `response_data` | array | List of lawsuits. Each item follows the [Lawsuit Schema](/en/schemas/lawsuit-object). |
| `response_data[].phase` | string | Current lawsuit phase — see table below. |
| `response_data[].status` | string | Current lawsuit status — see table below. |

***

### Full response example

<Accordion title="See response example">
  The response will be a JSON object with the data:

  ```json theme={null}
  {
      "has_lawsuits": true,
      "request_id": "c37cacba-41b5-4694-919f-4a937f2ea5df",
      "response_data": [
          {
              "code": "9999999-99.9999.9.99.9999",
              "justice": "5",
              "tribunal": "01",
              "instance": 2,
              "distribution_date": "2023-05-18T11:12:59.000Z",
              "tribunal_acronym": "TRT1",
              "secrecy_level": 0,
              "tags": {
                  "is_fallback_source": true,
                  "crawl_id": "28e00227-e41b-4c94-956e-7a0f105eabee"
              },
              "subjects": [
                  { "code": "13656", "name": "DOMÉSTICOS" }
              ],
              "classifications": [
                  { "code": "1009", "name": "RECURSO ORDINÁRIO TRABALHISTA" }
              ],
              "courts": [
                  { "code": "75580", "name": "GAB DES. GLAUCIA ZUCCARI FERNANDES BRAGA" }
              ],
              "parties": [
                  {
                      "name": "Test User",
                      "side": "Active",
                      "person_type": "Plaintiff",
                      "document": "99999999999",
                      "document_type": "CPF",
                      "lawyers": [
                          { "name": "Plaintiff's lawyer", "side": "Active", "person_type": "Lawyer" }
                      ],
                      "was_inferred": false
                  },
                  {
                      "name": "Test User",
                      "side": "Passive",
                      "person_type": "Defendant",
                      "document": "99999999999",
                      "document_type": "CPF",
                      "lawyers": [
                          { "name": "Defendant's lawyer", "side": "Passive", "person_type": "Lawyer" }
                      ],
                      "was_inferred": true
                  }
              ],
              "steps": [],
              "attachments": [],
              "related_lawsuits": [],
              "crawler": {
                  "source_name": "JTJ - BR - Document / Lawsuit - Auth",
                  "crawl_id": "28e00227-e41b-4c94-956e-7a0f105eabee",
                  "weight": 0,
                  "updated_at": "2024-03-18T19:21:02.466Z"
              },
              "amount": 7685.82,
              "last_step": {
                  "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                  "lawsuit_instance": 2,
                  "step_id": "JZzfEPTs10aeE+vpu+p+bkrz5K7enJhAM5kWattktHk=",
                  "step_date": "2024-03-18T19:21:02.466Z",
                  "private": false,
                  "steps_count": 1
              },
              "name": "Plaintiff Name X Defendant Name"
          }
      ]
  }
  ```
</Accordion>

> Full structure of each `response_data` item: see [Lawsuit Schema](/en/schemas/lawsuit-object).

## Common errors

| HTTP | When it happens | How to handle |
| :- | :- | :- |
| `400` | Invalid `search_type` or `search_key` / wrong format. | Validate the document before sending (e.g. 11 digits for CPF, 14 for CNPJ). |
| `401` | API Key missing or invalid. | Check the `api-key` header. |
| `404` | No lawsuits found. The response still comes with `has_lawsuits: false`. | Treat as no judicial exposure — not necessarily an error. |
| `429` | Rate limit exceeded (500 req/min). | Implement **exponential backoff** reading `X-RateLimit-Reset`. |
| `500` | Transient internal error. | Retry with backoff. If it persists, open a ticket with [support](https://api.whatsapp.com/send/?phone=5511920501949). |

## Next steps

* To **query a specific lawsuit by CNJ** with a freshness guarantee: [On-Demand Query](/en/cache-judit/on-demand).
* For **listing and filtering** with depth (advanced filters, side, classes): [Historical Query by document](/en/requests/request-document).
* For **aggregation** (counts by court/area/phase): [Grouped Query](/en/cache-judit/cache-grouped).
* To force **real-time read** at the court: [Asynchronous Query](/en/requests/requests).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.