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

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.

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" }
                    ]
                },
                {
                    "name": "Test User",
                    "side": "Passive",
                    "person_type": "Defendant",
                    "document": "99999999999",
                    "document_type": "CPF",
                    "lawyers": [
                        { "name": "Defendant's lawyer", "side": "Passive", "person_type": "Lawyer" }
                    ]
                }
            ],
            "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

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

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

​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

Most common filters (`search_params.filter`)

Request example (POST)

Step 2: Read the response

Full response example

Common errors

Next steps