Enums and Domains — Judit API - JUDIT

🤖 This document lists the literal values accepted and returned by the properties of the Judit API across its various Schemas. Remember that in the lawsuit object, the header properties (such as area, status, situation, secrecy_level) are nested inside the root response_data object, while side and person_type are inside the objects in the parties array.

Lawsuit Areas (`area`)

List of legal areas (Branches of Law) that a lawsuit or execution may have:

Public Law

DIREITO ADMINISTRATIVO E OUTRAS MATÉRIAS DE DIREITO PÚBLICO
DIREITO AMBIENTAL
DIREITO ELEITORAL
DIREITO INTERNACIONAL
DIREITO MARÍTIMO
DIREITO TRIBUTÁRIO

Criminal and Procedural Law

DIREITO PENAL
DIREITO PENAL MILITAR
DIREITO PREVIDENCIÁRIO
DIREITO PROCESSUAL CIVIL E DO TRABALHO

Special Matters

QUESTÕES DE ALTA COMPLEXIDADE, GRANDE IMPACTO E REPERCUSSÃO
REGISTROS PÚBLICOS

Secrecy Levels (`secrecy_level`)

Procedural secrecy classification system (integer from 0 to 5):

Level	Description	Permitted Access
`0`	Public	General public access.
`1`	Judicial secrecy	Parties and their associated lawyers.
`2`	Restricted (Court staff)	Judicial unit staff and parties.
`3`	Confidential (Chambers)	Magistrates, court clerks, and advisors.
`4`	Confidential (Magistrates and Clerks)	Only magistrates and court clerks.
`5`	Absolute secrecy	Exclusive to the magistrate in charge of the lawsuit.

Lawsuits with secrecy level > 0 may return limited payloads or payloads with obfuscated data, depending on the originating court and the credentials (Vault) used in the search.

Types of Justice (`justice_description`)

Classification of Brazilian Judiciary bodies:

Federal Justice and Superior Courts

SUPREMO TRIBUNAL FEDERAL
CONSELHO NACIONAL DE JUSTIÇA
SUPERIOR TRIBUNAL DE JUSTIÇA
TRIBUNAL REGIONAL FEDERAL

Specialized Justices

JUSTIÇA DO TRABALHO
JUSTIÇA ELEITORAL
JUSTIÇA MILITAR DA UNIÃO
JUSTIÇA MILITAR ESTADUAL

State Justice

JUSTIÇA ESTADUAL

Lifecycle: Status vs. Situation

The API returns two similar fields, but with distinct purposes, to indicate the health of the lawsuit.

1. Global Status (`status`)

Macro, standardized view of the lawsuit, ideal for filters and dashboards:

Value	Description	Behavior on Judit
`ATIVO`	Lawsuit running normally.	The crawler keeps collecting steps on every tracker run.
`FINALIZADO`	Lawsuit concluded or closed.	The crawler still monitors (in case the court reopens), but movements are rare.

2. Granular Situation (`situation`)

More specific and variable status, captured directly from the court’s header:

Value	Description	Behavior on Judit
`INICIAL`	Lawsuit recently filed.	Tends to generate many updates in the first days — a low tracker recurrence is recommended.
`SENTENÇA`	Lawsuit with a judgment issued.	Critical point — common target for `notification_filters.step_terms`.
`EXECUÇÃO OU CUMPRIMENTO`	Lawsuit in execution/collection phase.	Financial events (seizures, blocks) appear in the `steps`.
`TRÂNSITO JULGADO OU EM ACORDO`	Final decision with no further appeal possible.	Little follow-up activity; a high recurrence (e.g. 30 days) is enough.
`RECURSO`	Lawsuit awaiting appeal judgment.	Often generates new `lawsuit_cnj` at the 2nd instance.
`ARQUIVADO`	Lawsuit permanently archived.	The crawler keeps collecting, but rarely brings news.
`SUSPENSO`	Proceedings temporarily halted.	May return to `ATIVO` — keep the tracker active.
`SOBRESTADO`	Awaiting decision from a superior court.	Usually moves together with the lead-case decision at STF/STJ.
`CANCELADO`	Filing canceled.	The court removed the lawsuit — Judit marks it invalid on future runs.

Poles and Person Types (`side` and `person_type`)

When iterating over the parties arrays (whether in Lawsuits, Warrants, or Executions), you will encounter these classifications:

Procedural Pole (`side`)

Which side of the dispute the person is on.

ACTIVE: Active Pole (the one filing the action).
PASSIVE: Passive Pole (the one against whom the action is filed).
INTERESTED: Third parties or interested parties.
UNKNOWN: Not specified by the court.

Specific Role (`person_type`)

The exact legal qualification of the party. Common examples:

AUTOR / REQUERENTE / EXEQUENTE
RÉU / REQUERIDO / EXECUTADO / REEDUCANDO
ADVOGADO / DEFENSOR PÚBLICO
TESTEMUNHA / PERITO

Phases and Case Updates

Lawsuit Phases (`phase`)

CONHECIMENTO
EXECUÇÃO
RECURSO
FASE (Generic value used when the court does not specify the exact phase)

Case Update Codes (`step_type`)

The codes map to the CNJ Unified Procedural Table (TPU). Examples:

DISTRIBUIÇÃO
CITAÇÃO
CONTESTAÇÃO
SENTENÇA
RECURSO
ARQUIVAMENTO

Other Useful Enumerations

Brazilian States (`state`)

The API uses the 2-letter uppercase state acronym (UF) standard: AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO.

Document Types (`documents`)

Types of identifiers present in the documents arrays of parties or entities:

CPF: Individual (natural person).
CNPJ: Legal entity.
RG: General Registry (Brazilian ID card).
OAB: Bar Association registration (usually accompanied by the state acronym, e.g., OAB/SP).

Practical Usage Examples

Below, see the correct way to validate data by accessing the response_data object of a lawsuit.

1. Type Validation

// Example: Validating the status received from the API
const lawsuit = response.json(); // Root object

const validStatuses = ['ATIVO', 'FINALIZADO'];
const currentStatus = lawsuit.response_data.status; // ✅ Correct access

if (validStatuses.includes(currentStatus)) {
    console.log("Status recognized:", currentStatus);
}

# Example: Validating the secrecy level
valid_secrecy_levels = [0, 1, 2, 3, 4, 5]

# ✅ Correct access through the response_data dict
current_level = lawsuit.get('response_data', {}).get('secrecy_level')

is_valid = current_level in valid_secrecy_levels
print(f"Valid secrecy? {is_valid}")

2. Array Filtering

// Example: Filter lawsuits from a list that are only Public
const publicLawsuits = lawsuitsArray.filter(
  lawsuit => lawsuit.response_data.secrecy_level === 0
);

// Example: Filter only lawsuits from the State of SP
const spLawsuits = lawsuitsArray.filter(
  lawsuit => lawsuit.response_data.state === 'SP'
);

# Example: Filter lawsuits from a list that are only Public
public_lawsuits = [
    lawsuit for lawsuit in lawsuits_array 
    if lawsuit.get('response_data', {}).get('secrecy_level') == 0
]

# Example: Filter only lawsuits from the State of SP
sp_lawsuits = [
    lawsuit for lawsuit in lawsuits_array 
    if lawsuit.get('response_data', {}).get('state') == 'SP'
]

Next Steps

👉 Search Lawsuits: Use these enumerations as filter parameters in your searches.
👉 Arrest Warrant: See the schema for the arrest warrant object.
👉 Penal Execution: See the schema for penal executions and related enums.
👉 Glossary: Legal and technical terms used by the Judit API.

Getting Started

Core Concepts

Data Models (Schemas)

Asynchronous Requests

Synchronous Requests

Tracking

Registration Data

Criminal Records

File Transfer

Credentials Vault

Webhook

Resources

Enums and Domains — Judit API

Lawsuit Areas (`area`)

Secrecy Levels (`secrecy_level`)

Types of Justice (`justice_description`)

Lifecycle: Status vs. Situation

1. Global Status (`status`)

2. Granular Situation (`situation`)

Poles and Person Types (`side` and `person_type`)

Procedural Pole (`side`)

Specific Role (`person_type`)

Phases and Case Updates

Lawsuit Phases (`phase`)

Case Update Codes (`step_type`)

Other Useful Enumerations

Brazilian States (`state`)

Document Types (`documents`)

Practical Usage Examples

1. Type Validation

2. Array Filtering

Next Steps

​Lawsuit Areas (area)

​Secrecy Levels (secrecy_level)

​Types of Justice (justice_description)

​Lifecycle: Status vs. Situation

​1. Global Status (status)

​2. Granular Situation (situation)

​Poles and Person Types (side and person_type)

​Procedural Pole (side)

​Specific Role (person_type)

​Phases and Case Updates

​Lawsuit Phases (phase)

​Case Update Codes (step_type)

​Other Useful Enumerations

​Brazilian States (state)

​Document Types (documents)

​Practical Usage Examples

​1. Type Validation

​2. Array Filtering

​Next Steps

Lawsuit Areas (`area`)

Secrecy Levels (`secrecy_level`)

Types of Justice (`justice_description`)

Lifecycle: Status vs. Situation

1. Global Status (`status`)

2. Granular Situation (`situation`)

Poles and Person Types (`side` and `person_type`)

Procedural Pole (`side`)

Specific Role (`person_type`)

Phases and Case Updates

Lawsuit Phases (`phase`)

Case Update Codes (`step_type`)

Other Useful Enumerations

Brazilian States (`state`)

Document Types (`documents`)

Practical Usage Examples

1. Type Validation

2. Array Filtering

Next Steps