Synchronous Datalake Query (Hot Storage)

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.

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.

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 (async).

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 to get a real-time freshness guarantee at the court without leaving the synchronous flow.

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

Real-time validation

Onboarding, KYC, autocomplete — whenever you need an immediate response for the UI.

Interactive dashboards

Dashboards and BI listing lawsuits linked to a customer without forcing a court refresh.

Risk pre-filtering

Before firing an expensive async query, find out quickly whether it’s worth it.

Counts and aggregates

Combine with /lawsuits/count and /lawsuits/synthetic for analytics.

All synchronous queries accept filters (court, claim amount, classes, parties, dates, phase). See the full list at historical-query filters — the same search_params.filter object applies here.

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

{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99"
    }
}

{
    "search": {
        "search_type": "cnpj",
        "search_key": "99.999.999/9999-99"
    }
}

{
    "search": {
        "search_type": "oab",
        "search_key": "99999RJ"
    }
}

{
    "search": {
        "search_type": "name",
        "search_key": "John Smith"
    }
}

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

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

Query with party inference

{
    "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 has a response example with an inferred party.

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.

Most common filters (`search_params.filter`)

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

{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99",
        "search_params": {
            "filter": {
                "tribunals": { "keys": ["TJRJ"], "not_equal": false }
            }
        }
    }
}

{
    "search": {
        "search_type": "cnpj",
        "search_key": "00.000.000/0001-00",
        "search_params": {
            "filter": {
                "side": "Passive",
                "amount_gte": 50000
            }
        }
    }
}

{
    "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"
            }
        }
    }
}

{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99",
        "search_params": {
            "filter": {
                "tribunals": { "keys": ["TJSP"], "not_equal": true }
            }
        }
    }
}

Full list of accepted courts: see Historical-query filters.

Request example (POST)

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

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

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

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))
}

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.
`response_data[].phase`	string	Current lawsuit phase — see table below.
`response_data[].status`	string	Current lawsuit status — see table below.

Full response example

See response example

The response will be a JSON object with the data:

{
    "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"
        }
    ]
}

Full structure of each response_data item: see Lawsuit Schema.

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.

Next steps

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

Getting Started

Core Concepts

Data Models (Schemas)

Asynchronous Requests

Synchronous Requests

Tracking

Registration Data

Criminal Records

File Transfer

Credentials Vault

Webhook

Resources

Synchronous vs. asynchronous — which one?

When to use

Real-time validation

Interactive dashboards

Risk pre-filtering

Counts and aggregates

Step 1: Create the synchronous query (POST)

Synchronous query examples

Payload parameters

Party inference (`search_params.with_inferred_parties`)

Most common filters (`search_params.filter`)

Request example (POST)

Step 2: Read the response

Full response example

Common errors

Next steps

​Synchronous vs. asynchronous — which one?

​When to use

Real-time validation

Interactive dashboards

Risk pre-filtering

Counts and aggregates

​Step 1: Create the synchronous query (POST)

​Synchronous query examples

​Payload parameters

​Party inference (search_params.with_inferred_parties)

​Most common filters (search_params.filter)

​Request example (POST)

​Step 2: Read the response

​Full response example

​Common errors

​Next steps

Synchronous vs. asynchronous — which one?

When to use

Step 1: Create the synchronous query (POST)

Synchronous query examples

Payload parameters

Party inference (`search_params.with_inferred_parties`)

Most common filters (`search_params.filter`)

Request example (POST)

Step 2: Read the response

Full response example

Common errors

Next steps