Skip to main content

​
Basic Flow

The Judit API operates with both a synchronous and an asynchronous pattern:

​
Asynchronous requests:

  1. Create request (POST /requests) - Starts the query
  2. Wait for processing (GET /requests) - The API fetches data from the courts (track status)
  3. Fetch result (GET /responses) - Retrieves the processed data

​
Synchronous requests:

  1. Create request (POST /lawsuits) - Starts the query and returns the response immediately

​
Prerequisites

​
Environments and Base URLs

The Judit API is built on an architecture split by context to ensure better performance and organization. Before configuring your environment variables, identify the Base URL that corresponds to the module you want to integrate:
Base URLModule / ContextSupported Operations
https://requests.prod.judit.ioAsynchronous QueriesLawsuit query, Historical query, Arrest warrants, and Penal execution (request and response flows).
https://tracking.prod.judit.ioTrackingCreate, read, update, pause, delete, resume, and retrieve history of lawsuit tracking.
https://lawsuits.production.judit.ioSynchronous QueriesDatalake query (Hot storage), Lawsuit count, Grouped historical query, Bucket attachment retrieval, and Registration data.
https://crawler.prod.judit.ioCrawler & InfraCredentials Vault management.

​
Complete Example

​
1. Configure Environment Variables

Note: In the example below, we use the URL for Asynchronous Queries, but remember to replace it with the URL appropriate to your use case, according to the table above. 
export JUDIT_API_KEY="your-api-key-here"
export JUDIT_BASE_URL="https://requests.prod.judit.io"

​
2. Create a Request

curl -X POST "$JUDIT_BASE_URL/requests" \
  -H "api-key: $JUDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search": {
      "search_type": "cpf",
      "search_key": "999.999.999-99"
    }
  }'

​
3. Check the Request Status

curl -X GET "$JUDIT_BASE_URL/requests/$REQUEST_ID" \
  -H "api-key: $JUDIT_API_KEY"

​
4. Fetch the Results

When the status is completed, fetch the results: 
curl -X GET "$JUDIT_BASE_URL/responses?page=1" \
  -H "api-key: $JUDIT_API_KEY"

​
Available Query Types

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

​
Response Types

  • parties: Party information only
  • attachments: List of available attachments
  • step: Case updates

​
Advanced Filters

For more specific queries by document, you can use filters: 
{
  "search": {
    "search_type": "cpf",
    "search_key": "999.999.999-99",
    "search_params": {
      "filter": {
        "side":"passive",
        "amount_gte": 10000,
        "distribution_date_gte": "2024-10-10T00:00:00.000Z",
        "tribunals": {
          "keys": ["TJSP", "TJRJ"],
          "not_equal": false
        }
      }
    }
  }
}

​
Best Practices

​
1. Use Smart Caching

💡 Best Practice for Asynchronous Queries: If you are making asynchronous requests (via https://requests.prod.judit.io), using the cache parameter is strongly recommended. It drastically speeds up webhook response time and optimizes API consumption.
Set the cache_ttl_in_days parameter in your request body to avoid redundant lookups at the courts. This field defines for exactly how many days a result already stored in Judit’s base will be considered valid before forcing a new extraction. 
{
  "cache_ttl_in_days": 7  // Use cache for up to 7 days
}

​
2. Implement Retry with Backoff

  function sleep(ms) {
    return new Promise((resolve) => setTimeout(resolve, ms));
  } // Helper pause function based on setTimeout (native to JavaScript)

  async function retryWithBackoff(func, maxRetries = 3) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
      try {
        return await func();
      } catch (error) {
        if (attempt === maxRetries - 1) {
          throw error; // Last attempt failed, propagate the error
        }

        // Exponential backoff + random jitter
        const waitTime = (2 ** attempt) * 1000 + Math.random() * 1000;
        console.log(
          `Attempt ${attempt + 1} failed. Waiting ${waitTime.toFixed(0)}ms before retrying...`
        );
        await sleep(waitTime);
      }
    }
  }

​
Next Steps

  • Authentication: Configure authentication correctly
  • Endpoints: Explore all available endpoints
  • Support: Contact our technical support for more information.
Tip: For development, use the Postman Collection with ready-to-use Judit API examples.