Skip to main content
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.

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

Step 1: Create the Search Request (POST)

To initiate the asynchronous flow, make a POST request providing the desired document. POST https://requests.prod.judit.io/requests

Historical query examples

{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99"
    }
}
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.

Base Payload Parameters

ParameterTypeRequiredDescription
search.search_typestringYestype of entity to be searched: "cpf", "cnpj", "oab", or "name".
search.search_keystringYesThe value to be searched (e.g., "999.999.999-99", João Silva).
search.on_demandbooleanNoIf true, forces the search in real time at the courts instead of the Datalake.
cache_ttl_in_daysintegerNoConsiders the cache valid if the last extraction occurred within the last X days.
customer_keystringNoUser key in the Credentials Vault (used to access the courts with credentials registered in the credentials vault).
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.
{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99",
        "cache_ttl_in_days": 7
    }
}

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

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).
Acronym (Key)Official Name of the Body
STFSUPREMO TRIBUNAL FEDERAL
STJSUPERIOR TRIBUNAL DE JUSTIÇA
TSTTRIBUNAL SUPERIOR DO TRABALHO
TSETRIBUNAL SUPERIOR ELEITORAL
STMSUPERIOR TRIBUNAL MILITAR
CNJCONSELHO NACIONAL DE JUSTIÇA
CJFCONSELHO DA JUSTIÇA FEDERAL
CSJTCONSELHO SUPERIOR DA JUSTIÇA DO TRABALHO
Acronym (Key)Official Name of the Body
TRF1TRIBUNAL REGIONAL FEDERAL DA 1ª REGIÃO
TRF2TRIBUNAL REGIONAL FEDERAL DA 2ª REGIÃO
TRF3TRIBUNAL REGIONAL FEDERAL DA 3ª REGIÃO
TRF4TRIBUNAL REGIONAL FEDERAL DA 4ª REGIÃO
TRF5TRIBUNAL REGIONAL FEDERAL DA 5ª REGIÃO
Acronym (Key)Official Name of the Body
TRT1TRT DA 1ª REGIÃO (RJ)
TRT2TRT DA 2ª REGIÃO (SP - Capital)
TRT3TRT DA 3ª REGIÃO (MG)
TRT4TRT DA 4ª REGIÃO (RS)
TRT5TRT DA 5ª REGIÃO (BA)
TRT6TRT DA 6ª REGIÃO (PE)
TRT7TRT DA 7ª REGIÃO (CE)
TRT8TRT DA 8ª REGIÃO (PA/AP)
TRT9TRT DA 9ª REGIÃO (PR)
TRT10TRT DA 10ª REGIÃO (DF/TO)
TRT11TRT DA 11ª REGIÃO (AM/RR)
TRT12TRT DA 12ª REGIÃO (SC)
TRT13TRT DA 13ª REGIÃO (PB)
TRT14TRT DA 14ª REGIÃO (RO/AC)
TRT15TRT DA 15ª REGIÃO (SP - Campinas)
TRT16TRT DA 16ª REGIÃO (MA)
TRT17TRT DA 17ª REGIÃO (ES)
TRT18TRT DA 18ª REGIÃO (GO)
TRT19TRT DA 19ª REGIÃO (AL)
TRT20TRT DA 20ª REGIÃO (SE)
TRT21TRT DA 21ª REGIÃO (RN)
TRT22TRT DA 22ª REGIÃO (PI)
TRT23TRT DA 23ª REGIÃO (MT)
TRT24TRT DA 24ª REGIÃO (MS)
Acronym (Key)Official Name of the Body
TJACTRIBUNAL DE JUSTIÇA DO ACRE
TJALTRIBUNAL DE JUSTIÇA DO ALAGOAS
TJAPTRIBUNAL DE JUSTIÇA DO AMAPÁ
TJAMTRIBUNAL DE JUSTIÇA DO AMAZONAS
TJBATRIBUNAL DE JUSTIÇA DA BAHIA
TJCETRIBUNAL DE JUSTIÇA DO CEARÁ
TJDFTRIBUNAL DE JUSTIÇA DO DISTRITO FEDERAL E TERRITÓRIOS
TJESTRIBUNAL DE JUSTIÇA DO ESPÍRITO SANTO
TJGOTRIBUNAL DE JUSTIÇA DE GOIÁS
TJMATRIBUNAL DE JUSTIÇA DO MARANHÃO
TJMTTRIBUNAL DE JUSTIÇA DO MATO GROSSO
TJMSTRIBUNAL DE JUSTIÇA DO MATO GROSSO DO SUL
TJMGTRIBUNAL DE JUSTIÇA DE MINAS GERAIS
TJPATRIBUNAL DE JUSTIÇA DO PARÁ
TJPBTRIBUNAL DE JUSTIÇA DA PARAÍBA
TJPRTRIBUNAL DE JUSTIÇA DO PARANÁ
TJPETRIBUNAL DE JUSTIÇA DE PERNAMBUCO
TJPITRIBUNAL DE JUSTIÇA DO PIAUÍ
TJRJTRIBUNAL DE JUSTIÇA DO RIO DE JANEIRO
TJSPTRIBUNAL DE JUSTIÇA DE SÃO PAULO
TJRNTRIBUNAL DE JUSTIÇA DO RIO GRANDE DO NORTE
TJRSTRIBUNAL DE JUSTIÇA DO RIO GRANDE DO SUL
TJROTRIBUNAL DE JUSTIÇA DE RONDÔNIA
TJRRTRIBUNAL DE JUSTIÇA DE RORAIMA
TJSCTRIBUNAL DE JUSTIÇA DE SANTA CATARINA
TJSETRIBUNAL DE JUSTIÇA DE SERGIPE
Acronym (Key)Official Name of the Body
TRE-ACTRIBUNAL REGIONAL ELEITORAL DO ACRE
TRE-ALTRIBUNAL REGIONAL ELEITORAL DO ALAGOAS
TRE-APTRIBUNAL REGIONAL ELEITORAL DO AMAPÁ
TRE-AMTRIBUNAL REGIONAL ELEITORAL DO AMAZONAS
TRE-BATRIBUNAL REGIONAL ELEITORAL DA BAHIA
TRE-CETRIBUNAL REGIONAL ELEITORAL DO CEARÁ
TRE-DFTRIBUNAL REGIONAL ELEITORAL DO DISTRITO FEDERAL
TRE-ESTRIBUNAL REGIONAL ELEITORAL DO ESPÍRITO SANTO
TRE-GOTRIBUNAL REGIONAL ELEITORAL DE GOIÁS
TRE-MATRIBUNAL REGIONAL ELEITORAL DO MARANHÃO
TRE-MTTRIBUNAL REGIONAL ELEITORAL DO MATO GROSSO
TRE-MSTRIBUNAL REGIONAL ELEITORAL DO MATO GROSSO DO SUL
TRE-MGTRIBUNAL REGIONAL ELEITORAL DE MINAS GERAIS
TRE-PATRIBUNAL REGIONAL ELEITORAL DO PARÁ
TRE-PBTRIBUNAL REGIONAL ELEITORAL DA PARAÍBA
TRE-PRTRIBUNAL REGIONAL ELEITORAL DO PARANÁ
TRE-PETRIBUNAL REGIONAL ELEITORAL DE PERNAMBUCO
TRE-PITRIBUNAL REGIONAL ELEITORAL DO PIAUÍ
TRE-RJTRIBUNAL REGIONAL ELEITORAL DO RIO DE JANEIRO
TRE-RNTRIBUNAL REGIONAL ELEITORAL DO RIO GRANDE DO NORTE
TRE-RSTRIBUNAL REGIONAL ELEITORAL DO RIO GRANDE DO SUL
TRE-ROTRIBUNAL REGIONAL ELEITORAL DE RONDÔNIA
TRE-RRTRIBUNAL REGIONAL ELEITORAL DE RORAIMA
TRE-SCTRIBUNAL REGIONAL ELEITORAL DE SANTA CATARINA
TRE-SETRIBUNAL REGIONAL ELEITORAL DE SERGIPE
TRE-SPTRIBUNAL REGIONAL ELEITORAL DE SÃO PAULO
TRE-TOTRIBUNAL REGIONAL ELEITORAL DO TOCANTINS
Acronym (Key)Official Name of the Body
CJM1PRIMEIRA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM2SEGUNDA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM3TERCEIRA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM4QUARTA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM5QUINTA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM6SEXTA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM7SÉTIMA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM8OITAVA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM9NONA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM10DÉCIMA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM11DÉCIMA PRIMEIRA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM12DÉCIMA SEGUNDA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
TJM-MGTRIBUNAL DE JUSTIÇA MILITAR DO ESTADO DE MINAS GERAIS
TJM-RSTRIBUNAL DE JUSTIÇA MILITAR DO ESTADO DO RIO GRANDE DO SUL
TJM-SPTRIBUNAL DE JUSTIÇA MILITAR DO ESTADO DE SÃO PAULO
  • 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.

JSON Example: Including vs. Excluding Courts

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

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

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

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

Request Example (POST)

curl --location 'https://requests.prod.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
                }
            }
        }
    }
}'
Save the request_id (e.g., 05ee9825...) generated in the response of this call. It is your passport to the next steps.
🚀 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

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.prod.judit.io/requests/<REQUEST_ID>
cURL (Step 2)
curl --location 'https://requests.prod.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:
cURL
curl --location 'https://crawler.prod.judit.io/crawls/request/<request_id>?page=1&page_size=10' \
    --header 'api-key: <api-key>'
{
    "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"
        }
    ]
}

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.prod.judit.io/responses/

Dynamic URL Filters (Query Params)

These are the parameters you can concatenate to your final request:
Query ParamType / FormatDescription
request_idstring (UUID)Required. The ID generated in Step 1.
pageintegerCurrent page number for navigation (Default: 1).
page_sizeintegerNumber of results returned per page. Maximum allowed: 1000 (Recommended: 100).
response_typeJSON arrayDesired response type. E.g., ["lawsuit"].
codeJSON arrayFilters by specific lawsuit numbers. E.g., ["0601708-42..."].
instanceJSON arrayFilters by jurisdiction degree. E.g., [1, 2].
cachedbooleanReturns only cached lawsuits (true) or newly captured ones (false).
classifications_codeJSON arrayExact procedural class codes (E.g., ["437"]).
subjects_codeJSON arrayExact CNJ subject codes (E.g., ["6226"]).
created_at_gte / ltestring (Date)Filters by the date the lawsuit entered the Judit database.
orderJSON objectOrders the listing. E.g., {"created_at": "desc"}.
tags.criminalbooleanReturns true only for lawsuits in the criminal sphere.
# Returns the lawsuits using only the required parameter
curl -X GET "https://requests.prod.judit.io/responses?request_id=<YOUR_REQUEST_ID>" \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

The Response Format

The return provides the pagination keys and the page_data array, where each object contains the response_data (The Lawsuit Header).
request_status
string
Final status of the response (Must be completed).
page
integer
Current page of the search.
page_count
integer
Total number of lawsuits rendered on this page.
all_count
integer
Absolute total of lawsuits found and linked to the document.
all_pages_count
integer
Total number of available pages.
page_data
array
Array of objects. Each object contains the response_data key that holds the Lawsuit Header.
{
  "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",
              "instance": 1,
              "justice": "8",
              "tribunal": "19",
              "tribunal_acronym": "TJRJ",
              "classifications": [
                  { "code": "436", "name": "PROCEDIMENTO DO JUIZADO ESPECIAL CÍVEL" }
              ],
              "subjects": [
                  { "code": "6226", "name": "INCLUSÃO INDEVIDA EM CADASTRO DE INADIMPLENTES" }
              ],
              "amount": 28790,
              "parties": [
                  {
                      "name": "NOME DO CLIENTE",
                      "side": "Active",
                      "person_type": "Autor",
                      "document": "99999999999",
                      "document_type": "CPF"
                  }
              ]
          }
      }
  ]
}
Lawsuit not found: If the document has no linked lawsuits or if the filters are too restrictive, all_count will be 0 and the page_data array will return empty [].