Lawsuits summary

This endpoint returns a summary of the lawsuits that exist for the CPF (the Brazilian individual taxpayer number) or CNPJ (the Brazilian company taxpayer number) queried, grouping the counts by court, by segment of the judiciary and by year.

It is the counting lookup: it does not bring the cover sheet or the docket entries of the lawsuits. For the detail of each lawsuit, use Lawsuits.

🚧 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. The field names are the provider's, and there is no type conversion along the way — the tables on this page describe the fields, but they do not pin down types.

Request

GET /lawsuits-summary/v1

The version is required in the URL

There is no /lawsuits-summary route without a version. Calling without the version returns 404 even before authentication.

Parameters

Parameter	Description	Required
taxId	CPF or CNPJ of the party to the lawsuit	Yes
version	API version in the URL. Only v1 exists.	Yes

taxId accepts a CPF or a CNPJ, with or without the mask (123.456.789-09 or 12345678909). The mask is removed before the lookup. A document that fails the check-digit validation returns 422, and so does a missing taxId.

Unknown query parameters are ignored

This route reads only taxId. Any other parameter in the URL does not raise an error: it is simply ignored, and the response comes back 200 as usual.

Headers

Authorization: ApiKey <your-api-key>

Example request

GET /lawsuits-summary/v1?taxId=12345678909

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

Lookup by CNPJ:

curl -i -G 'https://api.nxcd.app/lawsuits-summary/v1' \
  --header 'Authorization: ApiKey YOUR_API_KEY' \
  --data-urlencode 'taxId=11.222.333/0001-81'

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 with the summary returned by the provider	Object[]
metadata	Object with the metadata of the request	Object
metadata.timeSpent	Request time, in milliseconds	Number

data is a list

Even though it brings a single summary, data comes as a list. When the provider returns nothing, the API delivers [].

Fields observed inside each item of data:

Field	Description
data[].total	Total of lawsuits found for the document queried
data[].totalByCourt	Count by court, with the court's acronym as the key
data[].totalByJustice	Count by segment of the judiciary, with the segment as the key
data[].totalByYear	Count by year, with the year as the key

The court acronyms that appear in totalByCourt are the same ones listed in Court or tribunal, on the Lawsuits page.

JSON examples

Here is a JSON example of the response.

Status Code: 200

{
  "id": "3aa55faf-0c97-40f0-a5a2-4a06ba6db92b",
  "version": "v1",
  "data": [
    {
      "total": 84,
      "totalByCourt": {
        "TRT-9": 14,
        "TST": 2,
        "TJ-SC": 51,
        "TJ-SP": 1,
        "STJ": 1,
        "TRT-12": 11,
        "TJ-RS": 3,
        "TJ-RJ": 1
      },
      "totalByJustice": {
        "TST": 2,
        "STJ": 1,
        "JUSTICA DO TRABALHO": 25,
        "JUSTICA ESTADUAL": 56
      },
      "totalByYear": {
        "2012": 4,
        "2011": 2,
        "2010": 2,
        "1998": 7,
        "2009": 1,
        "2008": 3,
        "1997": 1,
        "1995": 1,
        "2005": 1,
        "2004": 1,
        "2003": 2,
        "2002": 1,
        "1999": 13,
        "2001": 2,
        "2000": 4,
        "2022": 2,
        "2021": 2,
        "2020": 2,
        "2019": 3,
        "2018": 8,
        "2017": 5,
        "2016": 2,
        "2015": 5,
        "2014": 5,
        "2013": 5
      }
    }
  ],
  "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.lawsuitsSummary permission.
404 Not Found	The version informed in the URL does not exist, or the URL was called without a version. Only v1 is accepted.
422 Unprocessable Entity	taxId missing, or a CPF/CNPJ that 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 the taxId:

Status Code: 422

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

Example of a response with an invalid CPF or CNPJ:

Status Code: 422

{
  "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
v1	Recommended	The only version.

Any other value in place of v1 returns 404 with the message API version not found.

Related endpoint

• Lawsuits — the cover sheet and the docket entries of each lawsuit of the CPF/CNPJ.