Penal Execution Query

The Penal Execution Query identifies sentence-enforcement lawsuits (regime, progression, parole, pardon) linked to a CPF, Name or CNJ. You receive the Penal Execution structure, with specific roles (EXECUTED/REEDUCANDO), the last_step, and the sentence breakdown.

🤖 Same route as the lawsuit query: POST /requests with response_type: "execution". For the full structure, see Penal Execution Schema.

When to use

Reinforced KYC / background

Check whether the counterpart has an active or recent penal-execution case.

Public defense / criminal lawyers

Track current enforcement phase (regime, base dates) to plan progression motions.

Resocialization

For social and employability programs, identify active cases with prior consent.

Public compliance

Required checks for civil-service exams, government contracts or trusted positions.

This API lets interested parties check whether a penal execution order exists using CPF, name or lawsuit number (CNJ), ensuring the accuracy and relevance of the information retrieved.

Step 1: Create the request (POST)

POST https://requests.production.judit.io/requests

Examples by search type

{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99",
        "response_type": "execution"
    }
}

{
    "search": {
        "search_type": "name",
        "search_key": "John Smith",
        "response_type": "execution"
    }
}

{
    "search": {
        "search_type": "lawsuit_cnj",
        "search_key": "99999999-99.9999.9.99.9999",
        "response_type": "execution"
    }
}

{
    "search": {
        "search_type": "lawsuit_cnj",
        "search_key": "99999999-99.9999.9.99.9999",
        "response_type": "execution"
    },
    "with_attachments": true
}

response_type must always be "execution". search_type accepts "cpf", "cnpj", "name" or "lawsuit_cnj". The with_attachments: true flag only applies to CNJ searches.

Payload parameters

Parameter	Type	Required	Description
`search.search_type`	string	Yes	`"cpf"`, `"cnpj"`, `"name"` or `"lawsuit_cnj"`.
`search.search_key`	string	Yes	CPF, CNPJ, name or CNJ.
`search.response_type`	string	Yes	Always `"execution"`.
`with_attachments`	boolean	No	Only for `lawsuit_cnj`. If `true`, downloads attachments.
`callback_url`	string	No	HTTPS URL to receive the response via Webhook.

Request example (POST)

curl -X POST 'https://requests.production.judit.io/requests' \
  --header 'api-key: '"$JUDIT_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "search": {
      "search_type": "cpf",
      "search_key": "999.999.999-99",
      "response_type": "execution"
    }
  }'

const res = await fetch("https://requests.production.judit.io/requests", {
  method: "POST",
  headers: {
    "api-key": process.env.JUDIT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    search: {
      search_type: "cpf",
      search_key: "999.999.999-99",
      response_type: "execution",
    },
  }),
});
console.log(await res.json());

<?php
$ch = curl_init('https://requests.production.judit.io/requests');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'api-key: ' . getenv('JUDIT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'search' => [
            'search_type'   => 'cpf',
            'search_key'    => '999.999.999-99',
            'response_type' => 'execution',
        ],
    ]),
]);
echo curl_exec($ch);

import os, requests

resp = requests.post(
    "https://requests.production.judit.io/requests",
    headers={
        "api-key": os.environ["JUDIT_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "search": {
            "search_type": "cpf",
            "search_key": "999.999.999-99",
            "response_type": "execution",
        }
    },
    timeout=15,
)
resp.raise_for_status()
print(resp.json())

Creation response

{
    "request_id": "87d9f7bf-0071-41ee-a721-e6e1b4082bc9",
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99",
        "response_type": "execution"
    },
    "status": "pending",
    "created_at": "2024-03-14T07:35:14.272Z",
    "tags": { "potential_homonym": false }
}

The tags.potential_homonym field is true when there are signs the result may belong to a homonym — useful to validate before applying legal consequences.

Step 2: Retrieve the response

The query is asynchronous — wait for the Webhook or fetch via GET /responses?request_id={request_id}.

curl --location 'https://requests.production.judit.io/responses?request_id=<REQUEST_ID>' \
  --header 'api-key: '"$JUDIT_API_KEY"

resp = requests.get(
    f"https://requests.production.judit.io/responses?request_id={request_id}",
    headers={"api-key": os.environ["JUDIT_API_KEY"]},
)
print(resp.json())

Response structure

Field	Description
`code`	CNJ number of the execution lawsuit.
`classifications`	Classes (e.g. `EXECUÇÃO DA PENA`, `INDULTO`, `LIVRAMENTO CONDICIONAL`).
`subjects`	Subjects (e.g. `PENA PRIVATIVA DE LIBERDADE`).
`phase`	Current execution phase — see table below.
`status`	Status (`Ativo` / `Finalizado`).
`parties`	Active side (`AUTORIDADE`) and passive (`EXECUTADO` / `REEDUCANDO`).
`last_step`	Latest movement (date + content).
`steps`	Full movement history.
`tags.criminal`	`true` confirms it’s a criminal lawsuit.

Possible values for `phase`

Phase	Behavior
Inicial	Execution started, no progressions yet.
Em Cumprimento	Sentence actively being served.
Suspenso	Enforcement suspended by court decision.
Recurso	Appeal pending that affects the execution.
Trânsito em julgado ou acordo	Final decision or settlement (e.g. pardon).
Arquivado	Lawsuit archived after fulfillment or prescription.

Response example (CPF query)

See response example

{
    "page": 1,
    "page_data": [
        {
            "request_id": "1d3d84d9-2edb-4952-83dc-70a7d81487hj",
            "response_id": "9a4c8dee-e0d1-4cc5-8abb-bd5616265yu6",
            "origin": "api",
            "origin_id": "1d3d84d9-2edb-4952-83dc-70a7d81485ol",
            "response_type": "lawsuit",
            "response_data": {
                "amount": 0,
                "attachments": [],
                "classifications": [
                    {
                        "code": "386",
                        "name": "EXECUÇÃO DA PENA"
                    }
                ],
                "code": "99999999-99.9999.9.99.9999",
                "county": "MARINGÁ - 2ª VARA DA FAZENDA PÚBLICA",
                "courts": [
                    {
                        "name": "TJPR - Vara de Execução em Meio Aberto de Curitiba"
                    }
                ],
                "crawler": {
                    "source_name": "JSeeu - BR - Lawsuit - Auth - 1 instance",
                    "crawl_id": "a7fe1da7-6d2e-452f-9d36-115d80e9601a",
                    "weight": 10,
                    "updated_at": "2024-11-13T12:55:43.488Z"
                },
                "distribution_date": "2020-07-09T04:00:48.207Z",
                "free_justice": true,
                "instance": 1,
                "judge": "Usuário teste",
                "justice": "8",
                "last_step": {
                    "lawsuit_cnj": "99999999-99.9999.8.16.9999",
                    "lawsuit_instance": 1,
                    "content": "EXPEDIÇÃO DE CERTIDÃO GERAL Referente ao evento (seq. 417) RECEBIDOS OS AUTOS(13/08/2024 16:02:19). Identificador do Cumprimento: 9999.",
                    "tags": {
                        "crawl_id": "a7fe1da7-6d2e-452f-9d36-115d80e9601a"
                    },
                    "private": false,
                    "step_date": "2024-08-15T00:00:00.000Z",
                    "step_id": "2b837df6",
                    "steps_count": 418
                },
                "name": "ESTADO DO PARANÁ X USUÁRIO TESTE",
                "parties": [
                    {
                        "side": "Active",
                        "person_type": "AUTORIDADE",
                        "name": "ESTADO DO PARANÁ",
                        "main_document": "99999999999",
                        "tags": {
                            "crawl_id": "a7fe1da7-6d2e-452f-9d36-115d80e9601a"
                        },
                        "entity_type": "company",
                        "documents": [],
                        "lawyers": []
                    },
                    {
                        "side": "Passive",
                        "person_type": "EXECUTADO",
                        "name": "USUÁRIO TESTE",
                        "main_document": "99999999999",
                        "tags": {
                            "crawl_id": "a7fe1da7-6d2e-452f-9d36-115d80e9601a"
                        },
                        "entity_type": "person",
                        "documents": [],
                        "lawyers": []
                    }
                ],
                "related_lawsuits": [],
                "secrecy_level": 0,
                "steps": [],
                "subjects": [
                    {
                        "code": "7791",
                        "name": "PENA PRIVATIVA DE LIBERDADE"
                    }
                ],
                "tags": {
                    "datalake_id": "99999999999999999999",
                    "datalake_segment": "JUSTICA_ESTADUAL",
                    "crawl_id": "a7fe1da7-6d2e-452f-9d36-115d80e9601a",
                    "criminal": true,
                    "dictionary_updated_at": "2024-11-13T12:55:47.284Z"
                },
                "tribunal": "16",
                "tribunal_acronym": "TJPR"
            },
            "user_id": "7f8065a3-4891-428d-9456-dedfc12ff850",
            "created_at": "2024-11-13T12:55:47.885Z",
            "tags": {
                "dashboard_id": null
            }
        }
    ],
    "page_count": 1,
    "all_count": 1,
    "all_pages_count": 1
}

Below is an example response for a CNJ query:

See response example

{
    "page": 1,
    "page_data": [
        {
            "request_id": "a0c975a5-71ad-4013-9cdb-eefc670c9b8a",
            "response_id": "5d08159c-28e8-4c77-a20a-1a643a2eba87",
            "origin": "api",
            "origin_id": "a0c975a5-71ad-4013-9cdb-eefc670c9b8a",
            "response_type": "lawsuit",
            "response_data": {
                "amount": 0,
                "attachments": [],
                "classifications": [
                    {
                        "code": "386",
                        "name": "EXECUÇÃO DA PENA"
                    }
                ],
                "code": "99999999-99.9999.9.99.9999",
                "county": "MARINGÁ - 2ª VARA DA FAZENDA PÚBLICA",
                "courts": [
                    {
                        "name": "TJPR - Vara de Execução em Meio Aberto de Curitiba"
                    }
                ],
                "crawler": {
                    "source_name": "JSeeu - BR - Lawsuit - Auth - 1 instance",
                    "crawl_id": "730acd6f-a490-4153-a5e0-585e1c851eae",
                    "weight": 10,
                    "updated_at": "2024-11-13T13:33:16.264Z"
                },
                "distribution_date": "2020-07-09T04:00:48.207Z",
                "free_justice": true,
                "instance": 1,
                "judge": "USUÁRIO TESTE",
                "justice": "8",
                "last_step": {
                    "lawsuit_cnj": "99999999-99.9999.9.99.9999",
                    "lawsuit_instance": 1,
                    "content": "EXPEDIÇÃO DE CERTIDÃO GERAL Referente ao evento (seq. 417) RECEBIDOS OS AUTOS(13/08/2024 16:02:19). Identificador do Cumprimento: 0025.",
                    "tags": {
                        "crawl_id": "730acd6f-a490-4153-a5e0-585e1c851eae"
                    },
                    "private": false,
                    "step_date": "2024-08-15T00:00:00.000Z",
                    "step_id": "2b837df6",
                    "steps_count": 418
                },
                "name": "ESTADO DO PARANÁ X USUÁRIO TESTE",
                "parties": [
                    {
                        "side": "Active",
                        "person_type": "AUTORIDADE",
                        "name": "ESTADO DO PARANÁ",
                        "main_document": "99999999999",
                        "tags": {
                            "crawl_id": "730acd6f-a490-4153-a5e0-585e1c851eae"
                        },
                        "entity_type": "company",
                        "documents": [],
                        "lawyers": []
                    },
                    {
                        "side": "Passive",
                        "person_type": "EXECUTADO",
                        "name": "USUÁRIO TESTE",
                        "main_document": "99999999999",
                        "tags": {
                            "crawl_id": "730acd6f-a490-4153-a5e0-585e1c851eae"
                        },
                        "entity_type": "person",
                        "documents": [],
                        "lawyers": []
                    }
                ],
                "related_lawsuits": [],
                "secrecy_level": 0,
                "status": "Ativo",
                "phase": "Suspenso",
                "steps": [
                    {
                        "lawsuit_cnj": "99999999-99.9999.9.99.9999",
                        "lawsuit_instance": 1,
                        "content": "EXPEDIÇÃO DE CERTIDÃO GERAL Referente
ao evento (seq. 417). Identificador do Cumprimento: 0025.",
                            "step_date": "2024-08-15T00:00:00.000Z",
                            "step_id": "2b837df6"
                        }
                    ],
                    "tags": { "criminal": true },
                    "tribunal_acronym": "TJPR"
                }
            }
        ]
    }

Full structure: see Penal Execution Schema.

Common errors

HTTP	Reason	How to handle
`400`	Invalid payload.	Validate before sending.
`401`	API Key missing.	Check `api-key` header.
`404`	No penal execution found.	Treat as absent.
`429`	Rate limit exceeded.	Exponential backoff.

Next steps

Arrest Warrants — open orders.
Penal Execution Schema — full structure.
Webhooks — push delivery.

Getting Started

Core Concepts

Data Models (Schemas)

Asynchronous Requests

Synchronous Requests

Tracking

Registration Data

Criminal Records

File Transfer

Credentials Vault

Webhook

Resources

When to use

Reinforced KYC / background

Public defense / criminal lawyers

Resocialization

Public compliance

Step 1: Create the request (POST)

Examples by search type

Payload parameters

Request example (POST)

Creation response

Step 2: Retrieve the response

Response structure

Possible values for `phase`

Response example (CPF query)

Common errors

Next steps

​When to use

Reinforced KYC / background

Public defense / criminal lawyers

Resocialization

Public compliance

​Step 1: Create the request (POST)

​Examples by search type

​Payload parameters

​Request example (POST)

​Creation response

​Step 2: Retrieve the response

​Response structure

​Possible values for phase

​Response example (CPF query)

​Common errors

​Next steps

When to use

Step 1: Create the request (POST)

Examples by search type

Payload parameters

Request example (POST)

Creation response

Step 2: Retrieve the response

Response structure

Possible values for `phase`

Response example (CPF query)

Common errors

Next steps