🤖 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
| Property | Type | Description |
|---|
code | string | Unique lawsuit number in the CNJ standard. |
name | string | Description/Name of the lawsuit (e.g., “ACTIVE PARTY X PASSIVE PARTY”). |
area | string | Area of law (e.g., “DIREITO CIVIL”, “DIREITO ADMINISTRATIVO”). |
subject / subjects | array | Subjects of the case, based on the CNJ unified table. |
classifications | array | Procedural classes (e.g., “PROCEDIMENTO COMUM”), based on the CNJ. |
distribution_date | string | Date on which the lawsuit was filed/assigned at the court. |
instance | string | Degree of jurisdiction (e.g., “1ª INSTÂNCIA”, “2ª INSTÂNCIA”). |
judge | string | Name of the magistrate or responsible rapporteur. |
justice_description | string | Type of body (e.g., “JUSTIÇA ESTADUAL”, “JUSTIÇA FEDERAL”, “STJ”). |
tribunal_acronym | string | Official acronym of the originating court (e.g., “TJSP”, “TRF4”). |
county | string | County where the action is running. |
city / state | string | City and state (Federative Unit) of the county. |
amount | number | Value assigned to the case. |
phase | string | Procedural phase (e.g., “CONHECIMENTO”).
(Not returned in Document Query) |
status | string | Macro-status of the lawsuit (“ATIVO” or “FINALIZADO”).
(Not returned in Document Query) |
situation | string | Granular status captured directly in the court’s system. |
secrecy_level | integer | Level of secrecy (0 = Public. Levels 1 to 5 indicate degrees of restriction). |
2. Involved Parties (parties)
Array of objects representing the parties.
| Property | Type | Description |
|---|
name | string | Full name or company name of the party. |
main_document | string | Main CPF or CNPJ linked to the party. |
side | string | Pole in the lawsuit: ACTIVE (Plaintiff), PASSIVE (Defendant), INTERESTED, or UNKNOWN. |
person_type | string | Procedural role (e.g., “AUTOR”, “RÉU”, “TESTEMUNHA”, “TERCEIRO”). |
documents | array | List of objects with document_type (e.g., “CPF”, “CNPJ”) and document (the number). |
lawyers | array | List 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)
| Property | Type | Description |
|---|
step_id | string | Unique internal identifier of the case update. |
step_date | string | Date of the procedural case update. |
step_type | string | Code/Type of the case update mapped in the CNJ table. |
content | string | Full descriptive text of the case update (e.g., “Ato ordinatório praticado…”). |
private | boolean | Returns true if this specific case update runs under secrecy. |
4. Attached Documents (attachments)
(Array absent in Document Query responses)
| Property | Type | Description |
|---|
step_id | string | ID of the case update (step) that generated this attachment. |
attachment_date | string | Date the document was added. |
attachment_name | string | Title or name of the file (e.g., “Petição Inicial”, “Contestação”). |
extension | string | Format 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:
