Lawsuits

This endpoint looks up lawsuits in which the CPF (the Brazilian individual taxpayer number), the CNPJ (the Brazilian company taxpayer number) or the name queried is a party to the case, and returns the case cover sheet of the lawsuits found, with the docket entries summarized.

For the counts alone, without the cover sheet of the lawsuits, use Lawsuits summary.

🚧 data is passed through from the provider, with no transformation

The API does not reassemble the body of this response: whatever the provider returns inside data is delivered as is, inside the standard envelope. Three practical consequences:

The field names are in Portuguese, in the provider's vocabulary (numeroProcessoUnico, orgaoJulgador, movimentos), and not in the English camelCase used by the rest of the API.
Every block is optional. A block only shows up when the provider has data for it. Never assume a key exists: test before accessing it.
There is no type guarantee. Since there is no conversion along the way, the same field may arrive as a number or as text depending on where the data came from. That is why the tables on this page describe the fields but do not pin down types.

Request

GET /lawsuits/v2

Parameters

Parameter	Description	Required
taxId	CPF or CNPJ of one of the parties to the lawsuit	One of the three
partName	Name of one of the parties, by substring contained	One of the three
exactPartName	Exact name of one of the parties	One of the three

You must inform at least one of taxId, partName and exactPartName. Calling without any of the three returns 422 with the message One parameter is required: (taxId, partName, exactPartName).

More than one can be sent in the same call without raising an error, but only one is used. The order of precedence is taxId, then partName, then exactPartName: the first one filled in decides the lookup and the others are discarded.

Unknown query parameters are ignored

This route does not validate the list of parameters in the URL. An unknown name, or one typed by mistake, does not raise an error: it is simply ignored.

The `taxId` parameter — CPF or CNPJ of the party

The lookup by CPF/CNPJ finds every lawsuit in which the document searched for is a party, and returns the case cover sheet of the lawsuits found, with the docket entries summarized (without attachments).

The document can be sent with or without the mask (123.456.789-09 or 12345678909, 11.222.333/0001-81 or 11222333000181): the mask is removed before the lookup. A CPF or CNPJ that fails the check-digit validation returns 422 before any lookup is performed.

The `partName` parameter — name of the party, by substring contained

The lookup by name finds every lawsuit in which the name searched for appears among the parties.

TIP

The lookup by name brings every lawsuit that contains the name searched for among the parties. Searching for JOAO DA SILVA also returns JOAO DA SILVA SANTOS, JOAO DA SILVA FIGUEIREDO, and so on.

The `exactPartName` parameter — exact name of the party

The lookup by exact name brings only the lawsuits in which one of the parties has exactly the name informed.

Lookup parameters by attorney

The lookup that also takes the parties' attorneys into account — taxIdFull, name and exactName — does not exist yet. These three names are not read by the API: sending them has the same effect as any other unknown parameter, and a call that brings only one of them is refused with 422, for not having any of the three accepted parameters.

Parameter	Description	Status
taxIdFull	CPF/CNPJ (parties and attorneys)	Coming soon
name	Name (parties and attorneys)	Coming soon
exactName	Exact name (parties and attorneys)	Coming soon

Filter parameters

‼️ The filters are not being applied

The filter parameters below are accepted by the API, but they do not reach the provider: the call to the provider is assembled with the CPF, the CNPJ or the name of the lookup only, and the filters are discarded along the way.

In practice, today, the response is the same with or without a filter. Filter on your side, over the list returned, until the forwarding of the filters is restored.

Filter	Description	Examples
grade	Level or instance of the lawsuit. It is the only filter whose name is not the name of the field in the response: the matching field is `grauProcesso`.	`1` (from 1 to 4)
courts	Court of the lawsuit	`TJ-SC`, `TRT-1` (list in Court or tribunal)
partPole	Side of the case the party is on	`PASSIVO` or `ATIVO`
lawsuitStatuses	Status of the lawsuit	`EM TRAMITACAO` (list in Lawsuit status)
lawsuitFields	Field of law	`DIREITO DO TRABALHO` (list in Field of law)
topics	Subject matters of the lawsuit. Not listed on this page — see the CNJ unified court tables.	`ATRASO DE VOO`, `INDENIZACAO POR DANO MORAL`
lawsuitTypes	Class of the lawsuit. Not listed on this page — see the CNJ unified court tables.	`PROCEDIMENTO COMUM`, `ACAO PENAL`
distributionDate	Start date of the assignment of the lawsuit to a court, in the `YYYY-MM-DD` format	`2023-01-01`
distributionDateFinal	End date of the assignment of the lawsuit. Use it together with `distributionDate`, to bound a period, in the same format	`2023-12-31`
distributionDateEqual	Specific date of assignment, in the same format	`2023-08-08`
segment	Segment of the judiciary	`JUSTICA ESTADUAL`, `JUSTICA DO TRABALHO`, `JUSTICA FEDERAL`

The values follow the naming used in the tables of this page, without punctuation and without accents.

Headers

http

Authorization: ApiKey <your-api-key>

Example request

GET /lawsuits/v2?exactPartName=JOAO DA SILVA

bash

curl -i -G 'https://api.nxcd.app/lawsuits/v2' \
  --header 'Authorization: ApiKey YOUR_API_KEY' \
  --data-urlencode 'exactPartName=JOAO DA SILVA'

Lookup by CPF:

bash

curl -i -G 'https://api.nxcd.app/lawsuits/v2' \
  --header 'Authorization: ApiKey YOUR_API_KEY' \
  --data-urlencode 'taxId=12345678909'

Response

The envelope is the API standard:

Field	Description	Type
id	Unique identifier of the request	`String`
version	API version that served the call	`String`
data	List of the lawsuits found	`Object[]`
metadata	Object with the metadata of the request	`Object`
metadata.timeSpent	Request time, in milliseconds	`Number`

data is a list

Each item of data is a lawsuit. When nothing is found, data comes back empty: [].

Case cover sheet

Field	Description
data[].urlProcesso	URL of the lawsuit at the court queried
data[].numeroProcessoUnico	Unique lawsuit number, CNJ standard
data[].numeroProcessoAntigo	Lawsuit number prior to the CNJ standard
data[].statusObservacao	Status of the lawsuit according to the source (the court)
data[].grauProcesso	Level of the lawsuit (1, 2, 3, 4)
data[].juiz	Name of the judge of the lawsuit
data[].relator	Name of the reporting judge of the lawsuit
data[].revisores	List of the names of the reviewing judges, when there are any
data[].area	Area of the lawsuit (labor, civil...)
data[].sistema	System of the court queried
data[].segmento	Segment of the judiciary (state, federal...)
data[].tribunalOrigem	Court of origin of the lawsuit
data[].tribunal	Court of the lawsuit
data[].uf	State of the lawsuit or of the court
data[].orgaoJulgador	Judicial body hearing the lawsuit (court division)
data[].unidadeOrigem	Unit of origin of the lawsuit (judicial district)
data[].classeProcessual.nome	Name of the lawsuit class, CNJ standard
data[].classeProcessual.codigoCNJ	Code of the lawsuit class in the CNJ table
data[].assuntosCNJ	List of the subject matters of the lawsuit
data[].assuntosCNJ[].titulo	Name or title of the subject matter
data[].assuntosCNJ[].codigoCNJ	Code of the subject matter in the CNJ table
data[].dataDistribuicao	Date the lawsuit was assigned to a court
data[].dataAutuacao	Date the lawsuit was formally docketed
data[].valorCausa.moeda	Currency of the claim amount
data[].valorCausa.valor	Claim amount
data[].eTutelaAntecipada	Whether there is a preliminary injunction in the lawsuit
data[].eJusticaGratuita	Whether free legal aid was granted
data[].ePrioritario	Whether it is a priority lawsuit
data[].eSegredoJustica	Whether it runs under judicial seal
data[].eProcessoDigital	Whether it is a digital lawsuit
data[].dataProcessamento	Date the information was captured

Parties and attorneys

Field	Description
data[].partes	List of parties to the lawsuit
data[].partes[].tipo	Type of the party
data[].partes[].nome	Name of the party
data[].partes[].polo	Side of the party in the case (`ATIVO` or `PASSIVO`)
data[].partes[].cpf	CPF of the party
data[].partes[].cnpj	CNPJ of the party
data[].partes[].advogados	List of the attorneys of the party
data[].partes[].advogados[].tipo	Type of the attorney
data[].partes[].advogados[].nome	Name of the attorney
data[].partes[].advogados[].cpf	CPF of the attorney
data[].partes[].advogados[].cnpj	CNPJ of the attorney's law firm
data[].partes[].advogados[].oab.uf	State of the OAB registration (the Brazilian bar association)
data[].partes[].advogados[].oab.numero	OAB registration number
data[].partes[].advogados[].oab.tipo	Type of the OAB registration
data[].advogadosSemParte	List of attorneys with no related party
data[].advogadosSemParte[].tipo	Type of the attorney
data[].advogadosSemParte[].nome	Name of the attorney
data[].advogadosSemParte[].cpf	CPF of the attorney
data[].advogadosSemParte[].cnpj	CNPJ of the attorney's law firm
data[].advogadosSemParte[].oab.uf	State of the OAB registration
data[].advogadosSemParte[].oab.numero	OAB registration number
data[].advogadosSemParte[].oab.tipo	Type of the OAB registration

Field	Description
data[].movimentos	List of the docket entries of the lawsuit
data[].movimentos[].indice	Index of the docket entry
data[].movimentos[].data	Date of the docket entry
data[].movimentos[].nomeOriginal	Title of the docket entry
data[].movimentos[].descricao	Description of the docket entry
data[].movimentos[].movimentadoPor.nome	Name of whoever filed the entry in the lawsuit
data[].movimentos[].movimentadoPor.cargo	Position of whoever filed the entry in the lawsuit
data[].processosRelacionados	List of related lawsuits
data[].processosRelacionados[].numeroProcesso	Number of the related lawsuit

The docket entries come summarized

In this lookup, the list brings the summary of each entry, without the documents attached to it.

The `statusPredictus` block

The statusPredictus block gathers the classifications made by the provider's intelligence from reading the lawsuit in full.

Field	Description
data[].statusPredictus	Classifications made by the provider's intelligence
data[].statusPredictus.statusProcesso	Status of the lawsuit, according to the provider's classification
data[].statusPredictus.ramoDireito	Field or area of law of the lawsuit
data[].statusPredictus.dataArquivamento	Date the lawsuit was closed and archived
data[].statusPredictus.dataTransitoJulgado	Date the decision became final and unappealable
data[].statusPredictus.valorExecucao.moeda	Currency of the enforcement amount of the lawsuit
data[].statusPredictus.valorExecucao.valor	Enforcement amount of the lawsuit
data[].statusPredictus.julgamentos	List of the rulings handed down in the lawsuit
data[].statusPredictus.julgamentos[].dataJulgamento	Date of the ruling
data[].statusPredictus.julgamentos[].tipoJulgamento	Type of the ruling
data[].statusPredictus.julgamentos[].statusJulgamento	Status of the ruling
data[].statusPredictus.julgamentos[].diasAteJulgamento	Days between the assignment and the ruling
data[].statusPredictus.julgamentos[].justicaGratuita	Whether there was free legal aid
data[].statusPredictus.julgamentos[].tutelaAntecipada	Whether there was a preliminary injunction

The `statusExecucaoPena` block

The statusExecucaoPena block, inside statusPredictus, only shows up when there is a sentence involved in the lawsuit.

Field	Description
data[].statusPredictus.statusExecucaoPena.regimeAtual	Prison regime (closed, open, semi-open)
data[].statusPredictus.statusExecucaoPena.execucaoProvisoria	Whether the sentence is provisional
data[].statusPredictus.statusExecucaoPena.statusBnmp	Status coming from the BNMP, the Brazilian national prison monitoring database
data[].statusPredictus.statusExecucaoPena.percentualPenaCumprida	Percentage of the sentence already served
data[].statusPredictus.statusExecucaoPena.reuPreso	Whether the defendant is in custody
data[].statusPredictus.statusExecucaoPena.livramentoCondicional	Whether parole was granted until the sentence is extinguished
data[].statusPredictus.statusExecucaoPena.penaCumprida	Time of the sentence already served
data[].statusPredictus.statusExecucaoPena.penaRestante	Time remaining to serve out the sentence
data[].statusPredictus.statusExecucaoPena.penaTotal	Total sentence to be served
data[].statusPredictus.statusExecucaoPena.penaSubstitutiva	Whether there is an alternative sentence, such as a fine
data[].statusPredictus.statusExecucaoPena.medidaSeguranca	Security measure, when the defendant is found not criminally liable
data[].statusPredictus.statusExecucaoPena.beneficioArt75	Whether there is the benefit that caps time served at 30 years
data[].statusPredictus.statusExecucaoPena.situacaoSentenciado	Situation of the sentenced person
data[].statusPredictus.statusExecucaoPena.interrupcaoCumprimento	Whether serving the sentence was interrupted, as in the case of an escape
data[].statusPredictus.statusExecucaoPena.motivoInterrupcaoCumprimento	Reason for the interruption of the sentence
data[].statusPredictus.statusExecucaoPena.dataInicioInterrupcaoCumprimento	Date of the interruption of the sentence, if there was one
data[].statusPredictus.statusExecucaoPena.dataInicioCumprimento	Date the imprisonment began
data[].statusPredictus.statusExecucaoPena.foragido	Whether the person is a fugitive
data[].statusPredictus.statusExecucaoPena.extinto	Whether the sentence is extinguished

JSON examples

Here is a JSON example of the response.

Status Code: 200

json

{
  "id": "3aa55faf-0c97-40f0-a5a2-4a06ba6db92b",
  "version": "v2",
  "data": [
    {
      "urlProcesso": "https://esaj.tjsp.jus.br/cposg/search.do?conversationId=&paginaConsulta=0&cbPesquisa=NUMPROC&numeroDigitoAnoUnificado=0243906-91.2011&foroNumeroUnificado=0000&dePesquisaNuUnificado=0243905-91.2011.8.26.0000&dePesquisaNuUnificado=UNIFICADO&dePesquisa=&tipoNuProcesso=UNIFICADO&uuidCaptcha=&g-recaptcha-response=",
      "numeroProcessoUnico": "04239059120118260000",
      "statusObservacao": "ENCERRADO",
      "grauProcesso": 2,
      "relator": "DAMIAO DE OLIVEIRA",
      "area": "CRIMINAL",
      "sistema": "ESAJ-TJRJ-2G",
      "segmento": "JUSTICA ESTADUAL",
      "tribunal": "TJ-RJ",
      "uf": "RJ",
      "orgaoJulgador": "2ª CAMARA DE DIREITO CRIMINAL",
      "classeProcessual": {
        "nome": "HABEAS CORPUS CRIMINAL",
        "codigoCNJ": "307"
      },
      "assuntosCNJ": [
        {
          "titulo": "DIREITO PENAL-CRIMES CONTRA A VIDA-HOMICIDIO QUALIFICADO"
        }
      ],
      "dataDistribuicao": "2011-09-23T00:00:00",
      "partes": [
        {
          "tipo": "PACIENTE",
          "cpf": "12345678909",
          "nome": "JOAO DA SILVA"
        },
        {
          "tipo": "IMPETRANTE",
          "polo": "ATIVO",
          "cpf": "98765432100",
          "nome": "LUCIANO SOUSA"
        }
      ],
      "movimentos": [
        {
          "data": "2010-11-19T00:00:00",
          "indice": 50,
          "eMovimento": true,
          "nomeOriginal": ["PROCESSO CADASTRADO"]
        }
      ],
      "processosRelacionados": [
        {
          "numeroProcesso": "677353"
        }
      ],
      "eProcessoDigital": false,
      "dataProcessamento": "2022-07-13T11:36:30.133924",
      "statusPredictus": {
        "statusProcesso": "EM TRAMITACAO",
        "julgamentos": [],
        "dataTransitoJulgado": "2011-11-24T00:00:00",
        "ramoDireito": "DIREITO PENAL"
      },
      "unidadeOrigem": "DIREITO CRIMINAL"
    }
  ],
  "metadata": {
    "timeSpent": 4833
  }
}

WARNING

In this example the docket entries were left out, to make it easier to read. The example also does not bring the sentence enforcement block, since there is no sentence involved in the lawsuit used.

When nothing is found

Status Code: 200

json

{
  "id": "3aa55faf-0c97-40f0-a5a2-4a06ba6db92b",
  "version": "v2",
  "data": [],
  "metadata": {
    "timeSpent": 4833
  }
}

Response headers

Header	When it appears
`Nextid-ReqId`	On every response. Carries the request identifier, the same one as the `id` field of the body.

Errors

Code	When it happens
401 Unauthorized	API key missing, invalid, or without the `nextid.bureaus.lawsuits` permission.
404 Not Found	The version informed in the URL does not exist. Only `v2` reaches this lookup.
422 Unprocessable Entity	None of the parameters `taxId`, `partName` and `exactPartName` was informed, or `taxId` fails the check-digit validation.
500 Internal Server Error	Unexpected failure during processing, including a failure in the lookup at the provider.

Example of a response without any of the lookup parameters:

Status Code: 422

json

{
  "id": "3aa55faf-0c97-40f0-a5a2-4a06ba6db92b",
  "error": {
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "message": "One parameter is required: (taxId, partName, exactPartName)."
  }
}

Example of a response with an invalid CPF or CNPJ:

Status Code: 422

json

{
  "id": "3aa55faf-0c97-40f0-a5a2-4a06ba6db92b",
  "error": {
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "message": "Invalid taxId (CPF/CNPJ)"
  }
}

The format of the error responses is described in HTTP response codes.

Versions

Version	Status	What changes
v2	Recommended	The only version of this lookup.

/lawsuits/v2 is the only supported version of this lookup. Always state the version in the path of the call.

Lawsuits summary — the counts alone, by court, segment and year.

Additional information

Lawsuit status

The status is information generated by an internal intelligence that, from reading the lawsuit in full, including decisions and docket entries, classifies its status. These are the possible returns for the statusProcesso field or for lawsuitStatuses (when used as a lookup filter).

EM TRAMITACAO
EM GRAU DE RECURSO
SUSPENSO
ARQUIVAMENTO DEFINITIVO
ARQUIVAMENTO PROVISORIO
ARQUIVADO ADMINISTRATIVAMENTE
ARQUIVAMENTO

Field of law

Besides the status of the lawsuit, the intelligence also classifies the status of the ruling, the field of law the lawsuit belongs to, the enforcement amount and the sentence enforcement status, when there is a sentence involved. These are the possible returns for the ramoDireito field.

DIREITO A EDUCACAO
DIREITO ADMINISTRATIVO E OUTRAS MATERIAS DE DIREITO PUBLICO
DIREITO AMBIENTAL
DIREITO ASSISTENCIAL
DIREITO CIVIL
DIREITO DA CRIANCA E DO ADOLESCENTE
DIREITO DA SAUDE
DIREITO DO CONSUMIDOR
DIREITO DO TRABALHO
DIREITO ELEITORAL
DIREITO ELEITORAL E PROCESSO ELEITORAL DO STF
DIREITO INTERNACIONAL
DIREITO MARITIMO
DIREITO PENAL
DIREITO PENAL MILITAR
DIREITO PREVIDENCIARIO
DIREITO PROCESSUAL CIVIL E DO TRABALHO
DIREITO PROCESSUAL PENAL
DIREITO PROCESSUAL PENAL MILITAR
DIREITO TRIBUTARIO

Court or tribunal

Higher courts and councils

Federal regional courts

TRF-1
TRF-2
TRF-3
TRF-4
TRF-5
TRF-6

Federal courts

JF-AC
JF-AL
JF-AM
JF-AP
JF-BA
JF-CE
JF-DF
JF-ES
JF-GO
JF-MA
JF-MG
JF-MS
JF-MT
JF-PA
JF-PB
JF-PE
JF-PI
JF-PR
JF-RJ
JF-RN
JF-RO
JF-RR
JF-RS
JF-SC
JF-SE
JF-SP
JF-TO

State courts of justice

TJ-AC
TJ-AL
TJ-AM
TJ-AP
TJ-BA
TJ-CE
TJ-DFT
TJ-ES
TJ-GO
TJ-MA
TJ-MG
TJ-MS
TJ-MT
TJ-PA
TJ-PB
TJ-PE
TJ-PI
TJ-PR
TJ-RJ
TJ-RN
TJ-RO
TJ-RR
TJ-RS
TJ-SC
TJ-SE
TJ-SP
TJ-TO

Regional electoral courts

TRE-AC
TRE-AL
TRE-AM
TRE-AP
TRE-BA
TRE-CE
TRE-DF
TRE-DFT
TRE-ES
TRE-GO
TRE-MA
TRE-MG
TRE-MS
TRE-MT
TRE-PA
TRE-PB
TRE-PE
TRE-PI
TRE-PR
TRE-RJ
TRE-RN
TRE-RO
TRE-RR
TRE-RS
TRE-SC
TRE-SE
TRE-SP
TRE-TO

Regional labor courts

TRT-1
TRT-2
TRT-3
TRT-4
TRT-5
TRT-6
TRT-7
TRT-8
TRT-9
TRT-10
TRT-11
TRT-12
TRT-13
TRT-14
TRT-15
TRT-16
TRT-17
TRT-18
TRT-19
TRT-20
TRT-21
TRT-22
TRT-23
TRT-24

Military courts of justice

TJM-MG
TJM-RS
TJM-SP

Classifier

Lawsuits ​

Request ​

Parameters ​

The taxId parameter — CPF or CNPJ of the party ​

The partName parameter — name of the party, by substring contained ​

The exactPartName parameter — exact name of the party ​

Lookup parameters by attorney ​

Filter parameters ​

Headers ​

Example request ​

Response ​

Case cover sheet ​

Parties and attorneys ​

Docket entries and related lawsuits ​

The statusPredictus block ​

The statusExecucaoPena block ​

JSON examples ​

When nothing is found ​

Response headers ​

Errors ​

Versions ​

Related endpoint ​

Additional information ​

Lawsuit status ​

Field of law ​

Court or tribunal ​

Higher courts and councils ​

Federal regional courts ​

Federal courts ​

State courts of justice ​

Regional electoral courts ​

Regional labor courts ​

Military courts of justice ​

Lawsuits

Request

Parameters

The `taxId` parameter — CPF or CNPJ of the party

The `partName` parameter — name of the party, by substring contained

The `exactPartName` parameter — exact name of the party

Lookup parameters by attorney

Filter parameters

Headers

Example request

Response

Case cover sheet

Parties and attorneys

Docket entries and related lawsuits

The `statusPredictus` block

The `statusExecucaoPena` block

JSON examples

When nothing is found

Response headers

Errors

Versions

Related endpoint

Additional information

Lawsuit status

Field of law

Court or tribunal

Higher courts and councils

Federal regional courts

Federal courts

State courts of justice

Regional electoral courts

Regional labor courts

Military courts of justice