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.

🤖 The lawsuit object is returned in JSON format. The root property that contains the lawsuit metadata is called response_data. The history is returned in the steps array and the parties involved in the parties array. Remember that authentication to query this object is done via the api-key header, not a Bearer Token.
⚠️ Notice: Document Query (Historical Query)If you obtained this object through the Historical Query endpoint (Document-based Search), the phase and status properties of the Header will not be populated. Additionally, the steps (case updates) and attachments arrays are not returned.

​
General Structure

The lawsuit JSON is organized into 5 main blocks:
  • Header (response_data): Metadata, judge, county, case value, and status.
  • Parties (parties): Array containing the poles (active/passive), documents, and lawyers.
  • Case Updates (steps): Array with the chronological history of case updates.
  • Attachments (attachments): Array of documents (PDFs, HTML) linked to the case updates.
  • Related (related_lawsuits): Array of attached or linked lawsuits.

​
Data Dictionary

​
1. Lawsuit Header (response_data)

PropertyTypeDescription
codestringUnique lawsuit number in the CNJ standard.
namestringDescription/Name of the lawsuit (e.g., “ACTIVE PARTY X PASSIVE PARTY”).
areastringArea of law (e.g., “DIREITO CIVIL”, “DIREITO ADMINISTRATIVO”).
subject / subjectsarraySubjects of the case, based on the CNJ unified table.
classificationsarrayProcedural classes (e.g., “PROCEDIMENTO COMUM”), based on the CNJ.
distribution_datestringDate on which the lawsuit was filed/assigned at the court.
instancestringDegree of jurisdiction (e.g., “1ª INSTÂNCIA”, “2ª INSTÂNCIA”).
judgestringName of the magistrate or responsible rapporteur.
justice_descriptionstringType of body (e.g., “JUSTIÇA ESTADUAL”, “JUSTIÇA FEDERAL”, “STJ”).
tribunal_acronymstringOfficial acronym of the originating court (e.g., “TJSP”, “TRF4”).
countystringCounty where the action is running.
city / statestringCity and state (Federative Unit) of the county.
amountnumberValue assigned to the case.
phasestringProcedural phase (e.g., “CONHECIMENTO”).
(Not returned in Document Query)
statusstringMacro-status of the lawsuit (“ATIVO” or “FINALIZADO”).
(Not returned in Document Query)
situationstringGranular status captured directly in the court’s system.
secrecy_levelintegerLevel of secrecy (0 = Public. Levels 1 to 5 indicate degrees of restriction).

​
2. Involved Parties (parties)

Array of objects representing the parties.
PropertyTypeDescription
namestringFull name or company name of the party.
main_documentstringMain CPF or CNPJ linked to the party.
sidestringPole in the lawsuit: ACTIVE (Plaintiff), PASSIVE (Defendant), INTERESTED, or UNKNOWN.
person_typestringProcedural role (e.g., “AUTOR”, “RÉU”, “TESTEMUNHA”, “TERCEIRO”).
documentsarrayList of objects with document_type (e.g., “CPF”, “CNPJ”) and document (the number).
lawyersarrayList of lawyers associated with the party (contains name and oab).
Notice about Lawyers: If the court does not clearly specify which party the lawyer belongs to, the lawyer object will be listed directly in the main parties array, with a generic role/side.

​
3. Case Update History (steps)

(Array absent in Document Query responses)
PropertyTypeDescription
step_idstringUnique internal identifier of the case update.
step_datestringDate of the procedural case update.
step_typestringCode/Type of the case update mapped in the CNJ table.
contentstringFull descriptive text of the case update (e.g., “Ato ordinatório praticado…”).
privatebooleanReturns true if this specific case update runs under secrecy.

​
4. Attached Documents (attachments)

(Array absent in Document Query responses)
PropertyTypeDescription
step_idstringID of the case update (step) that generated this attachment.
attachment_datestringDate the document was added.
attachment_namestringTitle or name of the file (e.g., “Petição Inicial”, “Contestação”).
extensionstringFormat of the extracted file (e.g., “PDF”, “HTML”).

​
Complete JSON Example (Standard Query)

Below is the typical structural representation returned by the Judit API when querying a complete judicial lawsuit: 
{
  "response_data": {
    "code": "9999999-99.9999.9.99.9999",
    "name": "Ação de Cobrança Cível",
    "area": "DIREITO CIVIL",
    "distribution_date": "2024-01-15",
    "instance": "1ª INSTÂNCIA",
    "courts": "1ª VARA CÍVEL",
    "secrecy_level": 0,
    "subjects": ["COBRANÇA"],
    "classifications": ["PROCEDIMENTO COMUM CÍVEL"],
    "judge": "João Silva Santos",
    "justice_description": "JUSTIÇA ESTADUAL",
    "county": "SÃO PAULO",
    "tribunal_acronym": "TJSP",
    "city": "SÃO PAULO",
    "state": "SP",
    "situation": "ATIVA",
    "phase": "CONHECIMENTO",
    "status": "ATIVO",
    "amount": 50000.00
  },
  "parties": [
    {
      "name": "EMPRESA XYZ LTDA",
      "main_document": "12345678000190",
      "side": "ACTIVE",
      "person_type": "AUTOR",
      "documents": [
        { "document_type": "CNPJ", "document": "12345678000190" }
      ],
      "lawyers": [
        { "name": "Maria Advogada", "oab": "OAB/SP 123456" }
      ]
    }
  ],
  "steps": [
    {
      "step_id": "step_001_abc",
      "step_date": "2024-01-15",
      "step_type": "DISTRIBUIÇÃO",
      "content": "Processo distribuído por sorteio para a 1ª Vara Cível",
      "private": false
    }
  ],
  "attachments": [
    {
      "step_id": "step_001_abc",
      "attachment_date": "2024-01-15",
      "attachment_name": "Petição Inicial Cópia Autenticada",
      "extension": "PDF"
    }
  ],
  "related_lawsuits": []
}

​
Integration Examples (Retrieving a Lawsuit)

Important: In the examples below, we are using the Synchronous Query Base URL of our Datalake to retrieve the lawsuit object instantly. Remember to pass the api-key header. 
# Retrieve a specific lawsuit by CNJ
export JUDIT_API_KEY="your_key_here"

curl -X GET "https://lawsuits.production.judit.io/lawsuits/9999999-99.9999.9.99.9999" \
  -H "api-key: $JUDIT_API_KEY" \
  -H "Content-Type: application/json"

​
Next Steps

Now that you know the anatomy of a lawsuit, see how to capture them: