Legal and Technical Glossary — Judit API - JUDIT

Glossary organized in three layers: Brazilian legal concepts, payload properties (request/response fields) and internal architecture (datalake, hot storage, crawler).

🤖 Use this glossary as a quick reference. For the full structure of each object (Lawsuit, Entity, Warrant, Penal Execution), check the Schemas.

Brazilian legal concepts

Official identifiers

Term	Meaning
CNJ	National Council of Justice — unique lawsuit number in pattern `NNNNNNN-DD.AAAA.J.TR.OOOO` (20 digits).
CPF	Individual taxpayer ID (Federal Revenue). 11 digits.
CNPJ	Legal-entity registry. 14 digits. Accepts the new alphanumeric format (RFB IN 2229/24).
OAB	Brazilian Bar Association ID. Lawyer identifier in `<number><state>` format (e.g. `123456SP`).
RJI	Individual Judicial Registry assigned by BNMP 2.0 to each wanted person.

Lawsuit structure

Term	Meaning
Lawsuit cover	Header set: number, class, subject, claim amount, parties, distribution date, district, judge.
Step	Each movement/entry recorded in the case files. Listed chronologically.
Party	Person, company or authority involved (Plaintiff, Defendant, Interested, Lawyer).
Side	Party side: `Active` (Plaintiff), `Passive` (Defendant), `Interested` (Third party).
County (comarca)	Territorial division of the judiciary — jurisdiction of a 1st-instance judge.
Court (vara)	Jurisdictional unit within a county (Civil, Criminal, Labor, etc.).
Instance	Lawsuit degree: 1 (originating) or 2 (appeal).
Class	Procedure type (e.g. Common Civil Procedure, Writ of Mandamus).
Subject	Topic/matter as per the CNJ table (e.g. Traffic Accident).
Distribution	Date when the lawsuit was officially assigned to a court.
Final judgment (trânsito em julgado)	Final decision with no appeals available.

Justices and courts

Term	Meaning
State Justice	TJ of each state — general civil/criminal jurisdiction.
Federal Justice	TRFs (1 to 6) — Union, agencies, federal disputes.
Labor Justice	TST + TRTs (1 to 24) — labor relations.
Electoral Justice	TSE + TREs — elections and electoral crimes.
Military Justice	STM + State Military Justice — military crimes.
Superior Courts	STF, STJ, TST, TSE, STM.
BNMP	National Arrest Warrant Database — CNJ database with active warrants.

Full list: Court Coverage.

Secrecy and criminal justice

Term	Meaning
Judicial secrecy	Lawsuit restricted to bound parties. Requires the lawyer’s credential (see Credentials Vault).
`secrecy_level` 0–5	Secrecy scale. `0` = public; `5` = absolute secrecy.
Arrest warrant	Judicial arrest order (preventive, temporary, definitive, recapture). Collected from BNMP.
Penal execution	Sentence-enforcement lawsuit, with phases like progression and parole.

Payload properties (request/response)

Request identification

Field	What it is
`request_id`	UUID generated when you create a request (`POST /requests`).
`response_id`	UUID of each response generated for a request (multiple possible).
`tracking_id`	UUID of a tracker (`POST /tracking`).
`callback_id`	Unique UUID per webhook delivery (use for idempotency).
`origin_id`	UUID linking child requests to a parent request.

Cache and freshness

Field	What it is
`cache_ttl_in_days`	How many days a cached result stays valid before forcing a fresh fetch.
`cached_response`	`true` = response from datalake; `false` = fresh fetch from court. See Webhook.
`is_fallback_source`	Indicates the data came from a secondary source (e.g. court was offline).
`dictionary_updated_at`	Date of the last dictionary update (subjects, classes).

Field	What it is
`search_type`	`cpf`, `cnpj`, `oab`, `name`, `lawsuit_cnj`, `lawsuit_id`, `rji` or `custom`.
`search_key`	Concrete value to search (CPF, CNPJ, CNJ number, etc.).
`response_type`	Expected response format: `lawsuit`, `entity`, `warrant`, `execution`.
`on_demand`	If `true`, forces real-time fetch (higher cost). Applies to `/entities` and historical queries.
`with_attachments`	If `true`, downloads attachments (only for `search_type: lawsuit_cnj` or warrant).
`reveal_partners_documents`	(CNPJ) Returns partner CPFs/CNPJs unmasked.
`customer_key`	Key in Credentials Vault to access lawsuits under judicial secrecy.

Filters (search_params.filter)

Field	What it is
`side`	Party side: `Active`, `Passive`, `Interested`, `Unknown`.
`amount_gte` / `amount_lte`	Minimum/maximum claim amount.
`distribution_date_gte` / `_lte`	Distribution-date window.
`last_step_date_gte` / `_lte`	Last-step date window.
`tribunals.keys` + `not_equal`	Includes (false) or excludes (true) courts — see Coverage.
`subject_codes.keys` + `not_equal`	Official CNJ subject codes.
`classification_codes.keys` + `not_equal`	Official CNJ class codes.
`party_names`	Filter by party name.
`party_documents`	Filter by party CPF/CNPJ.

Pagination and listing

Field	What it is
`page`	Current page (1-based).
`page_size`	Items per page (max 1000).
`page_count`	Total items in this page.
`all_count`	Absolute total of items matched by the filter.
`all_pages_count`	Total pages considering `page_size`.
`page_data`	Array with current-page items.

Tracking

Field	What it is
`recurrence`	Interval (in days) between tracker runs.
`notification_emails`	Emails that receive notifications on every update.
`notification_filters.step_terms`	Terms that filter which steps trigger notifications.
`tracked_items_count`	Total items (lawsuits) the tracker is following.
`hour_range`	Hour of the day when the tracker runs.

Entity (registration data)

Field	What it is
`entity_id`	Internal UUID.
`entity_type`	`person` (PF) or `company` (PJ).
`main_document`	CPF (PF) or CNPJ (PJ).
`aka_names`	Other associated names/aliases.
`addresses`	List of addresses.
`contacts`	Phones and emails.
`parents`	(PF) Parents (mother/father).
`partners`	(PJ) Partners and administrators.
`branch_activities`	(PJ) CNAE activities.
`legal_nature`	(PJ) Legal nature.
`revenue_service_active`	Status with the Federal Revenue.

Warrant (arrest)

Field	What it is
`warrant_type`	`warrant_of_arrest` or `recapture`.
`arrest_type`	`preventive`, `temporary`, `definitive`.
`law_type.number` / `description`	Infringed law/articles.
`issue_date` / `expiration_date`	Issue and expiration dates.
`duration_years` / `_months` / `_days`	Calculated sentence.
`regime`	`Aberto`, `Semiaberto`, `Fechado`.
`judgementSummary`	Sentence/order text.

Errors

Field	What it is
`error.name`	Error name (e.g. `HttpBadRequestError`, `HttpNotFoundError`).
`error.message`	Error group (e.g. `BAD_REQUEST`).
`error.data`	Validation details/messages.
`LAWSUIT_NOT_FOUND`	`application_error` returned when a search has no result.

Judit internal architecture

Components

Term	What it is
Datalake	Central repository of lawsuits collected by Judit (≈ hundreds of millions of lawsuits).
Hot Storage	High-performance cache layer — source of synchronous queries.
Crawler	Robot that collects data at courts. Each collection generates a `crawl_id`.
On-Demand	Real-time fetch mode, bypassing the datalake.

Services (microservices)

Service	URL	Function
Requests	`requests.production.judit.io`	Create and read async requests.
Tracking	`tracking.production.judit.io`	Continuous monitoring.
Lawsuits	`lawsuits.production.judit.io`	Synchronous datalake, registration data, attachments.
Crawler	`crawler.prod.judit.io`	Credentials Vault.
User	(internal)	Auth and callback management.

Webhook events

Event	When it fires
`response_created`	The only `event_type` sent: each new response generated (cache, court or tracker).

The end of a request flow arrives as response_created with response_type: "application_info" and response_data.code: 600 (REQUEST_COMPLETED). Trackers use reference_type: "tracking".Details at Webhooks.

Tags and metadata

Term	What it is
`crawl_id`	UUID of the crawler run that collected the data.
`dashboard_id`	(Optional) Link with specific dashboards.
`criminal`	`true` for criminal-sphere lawsuits.
`is_fallback_source`	Data collected from a secondary source.
`revenue_update_date`	Last Federal Revenue update for the entity.
`datalake_id` / `datalake_segment`	Internal datalake identifiers.
`possible_homonym` / `potential_homonym`	Indicates suspected homonym in the result.

Next steps

Court Coverage — acronyms to use in filters.
Lawsuit Schema — full structure of the main object.
Enums — literal values accepted per property.
FAQ — frequently asked questions.

Getting Started

Core Concepts

Data Models (Schemas)

Asynchronous Requests

Synchronous Requests

Tracking

Registration Data

Criminal Records

File Transfer

Credentials Vault

Webhook

Resources

Legal and Technical Glossary — Judit API

Brazilian legal concepts

Payload properties (request/response)

Judit internal architecture

Next steps

​Brazilian legal concepts

​Payload properties (request/response)

​Judit internal architecture

​Next steps

Brazilian legal concepts

Payload properties (request/response)

Judit internal architecture

Next steps