Skip to main content

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.

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?

TraitSynchronous (Hot Storage)Asynchronous (Requests)
Latencyms (immediate)seconds to minutes
SourceJudit datalake (cache)Live court
FreshnessLast Judit collectionCourt state right now
WebhookN/AYes, optional
CostLowerHigher
Best forQuick validation, dashboards, interactive searchDue 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"
    }
}
For name queries homonyms are possible. Whenever feasible, prefer CPF, CNPJ or OAB for accuracy.

​
Payload parameters

ParameterTypeRequiredDescription
search.search_typestringYesEntity type: "cpf", "cnpj", "oab" or "name".
search.search_keystringYesValue to search (e.g. "999.999.999-99", "John Smith").
search.search_params.filterobjectNoStructural 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 }
            }
        }
    }
}
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"
    }
  }'

​
Step 2: Read the response

The response comes in the body of the same POST (no polling). Main fields:
FieldTypeDescription
has_lawsuitsbooleantrue when lawsuits were found in the datalake.
request_idstringUnique query identifier — useful for auditing.
response_dataarrayList of lawsuits. Each item follows the Lawsuit Schema.
response_data[].phasestringCurrent lawsuit phase — see table below.
response_data[].statusstringCurrent lawsuit status — see table below.

​
Full 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

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

​
Next steps