> ## Documentation Index
> Fetch the complete documentation index at: https://docs.judit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Tracking with Filters

> Set up trackers with advanced filters (court, claim amount, distribution date, parties) to follow only what matters on the Judit API.

export const CustomTrackingAnimation = () => <iframe sandbox="allow-scripts" scrolling="no" style={{
  width: '100%',
  height: '540px',
  border: 'none',
  borderRadius: '12px',
  display: 'block',
  margin: '20px 0'
}} srcDoc={`<!doctype html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{width:100%;height:100%;overflow:hidden;background:#090c0d}canvas{display:block;width:100%;height:100%}</style></head><body><canvas id="c"></canvas><script>(function(){
var A='#4FD1C5',J='#1FC16B',T='#E0A82E',M='#7A8599';
var BG='#090c0d',TXT='#e5e7eb',NF='#111827',PT='#0a1020';
var TOTAL=12.0;
var XP={app:0.13,judit:0.50,court:0.87};
var NW=88,NH=42;
var NODES=[{id:'app',label:'Your App',col:A},{id:'judit',label:'Judit API',col:J},{id:'court',label:'Courts',col:T}];
var STEPS=[
  {fr:'app',to:'judit',label:'POST /tracking',note:'{search_type:"custom", filter:{...}}',col:A,ts:1.0,te:1.8,yp:0.30},
  {fr:'judit',to:'app',label:'201 {tracking_id}',note:'status: created',col:J,ts:2.3,te:3.1,yp:0.42},
  {sep:true,label:'↻  automatic execution every N days',yp:0.52},
  {fr:'judit',to:'court',label:'checks for new lawsuits',note:'matching configured filters',col:T,ts:4.8,te:5.6,yp:0.60},
  {fr:'court',to:'judit',label:'new lawsuit found',note:'',col:J,ts:6.1,te:6.9,yp:0.72},
  {fr:'judit',to:'app',label:'webhook',note:'event: new_lawsuit',col:J,ts:7.4,te:8.2,yp:0.84}
];
var cv=document.getElementById('c');
function setup(){var dpr=Math.min(window.devicePixelRatio||1,2),r=cv.getBoundingClientRect(),W=r.width||window.innerWidth,H=r.height||window.innerHeight;cv.width=Math.max(1,W*dpr);cv.height=Math.max(1,H*dpr);var ctx=cv.getContext('2d');ctx.setTransform(dpr,0,0,dpr,0,0);return{ctx:ctx,w:W,h:H};}
function ease(t){return t<0.5?2*t*t:1-Math.pow(-2*t+2,2)/2;}
function rr(ctx,x,y,w,h,r){ctx.beginPath();ctx.moveTo(x+r,y);ctx.arcTo(x+w,y,x+w,y+h,r);ctx.arcTo(x+w,y+h,x,y+h,r);ctx.arcTo(x,y+h,x,y,r);ctx.arcTo(x,y,x+w,y,r);ctx.closePath();}
function gx(n,w){return n==='app'?w*XP.app:n==='judit'?w*XP.judit:w*XP.court;}
function eg(fr,to,w){var fx=gx(fr,w),tx=gx(to,w),d=tx>fx?1:-1;return{x1:fx+d*NW/2,x2:tx-d*NW/2,d:d};}
function dPkt(ctx,x,y,lbl,col){var pw=Math.max(36,lbl.length*6+14),ph=20;ctx.save();ctx.shadowColor=col;ctx.shadowBlur=18;rr(ctx,x-pw/2,y-ph/2,pw,ph,5);ctx.fillStyle=col;ctx.fill();ctx.shadowBlur=0;ctx.fillStyle=PT;ctx.font='bold 9px monospace';ctx.textAlign='center';ctx.textBaseline='middle';ctx.fillText(lbl,x,y+0.5);ctx.restore();}
function draw(ctx,w,h,t){
  var ct=t%TOTAL,bx1=w*0.02,bx2=w*0.98;
  ctx.fillStyle=BG;ctx.fillRect(0,0,w,h);
  var nodeY=h*0.21;
  ctx.fillStyle=J;ctx.font='bold 12px Inter,system-ui,sans-serif';ctx.textAlign='center';ctx.textBaseline='middle';ctx.fillText('Custom Tracking with Filters',w/2,h*0.04);
  ctx.fillStyle=M;ctx.font='10px Inter,system-ui,sans-serif';ctx.fillText('Judit detects new lawsuits matching the configured filters',w/2,h*0.09);
  for(var i=0;i<NODES.length;i++){var n=NODES[i],lx=gx(n.id,w);ctx.save();ctx.strokeStyle=n.col;ctx.globalAlpha=0.35;ctx.lineWidth=1;ctx.setLineDash([4,7]);ctx.beginPath();ctx.moveTo(lx,nodeY+NH/2);ctx.lineTo(lx,h*0.94);ctx.stroke();ctx.restore();}
  for(var si=0;si<STEPS.length;si++){var s=STEPS[si],sy=h*s.yp;if(s.sep){ctx.save();ctx.strokeStyle='rgba(255,255,255,0.28)';ctx.lineWidth=1;ctx.setLineDash([3,5]);ctx.beginPath();ctx.moveTo(bx1,sy);ctx.lineTo(bx2,sy);ctx.stroke();ctx.fillStyle='rgba(255,255,255,0.05)';rr(ctx,bx1,sy-8,s.label.length*6.2+14,16,3);ctx.fill();ctx.fillStyle=M;ctx.font='10px monospace';ctx.textAlign='left';ctx.textBaseline='middle';ctx.fillText(s.label,bx1+5,sy);ctx.restore();continue;}var e=eg(s.fr,s.to,w),x1=e.x1,x2=e.x2,d=e.d,clx=(x1+x2)/2;var state=ct<s.ts?'pre':ct>s.te?'done':'live',alpha=state==='pre'?0.10:state==='done'?0.55:1.0;ctx.save();ctx.globalAlpha=alpha;ctx.strokeStyle=s.col;ctx.lineWidth=1.5;ctx.setLineDash([]);ctx.beginPath();ctx.moveTo(x1,sy);ctx.lineTo(x2,sy);ctx.stroke();ctx.fillStyle=s.col;ctx.beginPath();ctx.moveTo(x2,sy);ctx.lineTo(x2-d*7,sy-4);ctx.lineTo(x2-d*7,sy+4);ctx.closePath();ctx.fill();ctx.fillStyle=TXT;ctx.font='bold 10px monospace';ctx.textAlign='center';ctx.textBaseline='bottom';ctx.fillText(s.label,clx,sy-4);if(s.note){ctx.fillStyle=M;ctx.font='9px monospace';ctx.fillText(s.note,clx,sy-16);}ctx.restore();if(state==='live'){var p=ease((ct-s.ts)/(s.te-s.ts));dPkt(ctx,x1+(x2-x1)*p,sy+14,s.label,s.col);}}
  for(var i=0;i<NODES.length;i++){var nd=NODES[i],px=gx(nd.id,w);ctx.save();ctx.shadowColor=nd.col;ctx.shadowBlur=14;rr(ctx,px-NW/2,nodeY-NH/2,NW,NH,8);ctx.fillStyle=NF;ctx.fill();ctx.shadowBlur=0;ctx.strokeStyle=nd.col;ctx.lineWidth=1.8;ctx.stroke();ctx.fillStyle=nd.col;ctx.font='bold 11px Inter,system-ui,sans-serif';ctx.textAlign='center';ctx.textBaseline='middle';ctx.fillText(nd.label,px,nodeY);ctx.restore();}
}
var dim,t0;
function loop(){var t=(performance.now()-t0)/1000;draw(dim.ctx,dim.w,dim.h,t);requestAnimationFrame(loop);}
window.addEventListener('load',function(){dim=setup();t0=performance.now();loop();});
window.addEventListener('resize',function(){dim=setup();});
})()\x3c/script></body></html>`} />;

<Info>
  **New CNPJ format (IN 2229/24)**

  Judit already accepts the new **alphanumeric CNPJ** format in compliance with the [Brazilian Federal Revenue Normative Instruction No. 2229/2024](https://normasinternet2.receita.fazenda.gov.br/#/consulta/externa/141102).

  * **Zero effort:** no changes are required in your integration.
  * **Test environment:** use the document `A1B2C3D4/E5F6-68` to validate the flow and receive a mock lawsuit in response.
</Info>

**Custom Tracking** watches for new lawsuits based on **structural filters** (court, class, area, claim amount, parties, dates) — without needing a specific document. Use it when you want to be notified about new lawsuits in a **universe defined by criteria**, not by a party.

> 🤖 Endpoint: `POST https://tracking.production.judit.io/tracking` with `search_type: "custom"` and `search_params.filter` defined. Pricing differs from document tracking — confirm with the commercial team.

<CustomTrackingAnimation />

## When to use

<CardGroup cols={2}>
  <Card title="Market intelligence" icon="binoculars">
    Detect new lawsuits in a specific class at a court/state to drive trend analysis.
  </Card>

  <Card title="Proactive defense" icon="shield-check">
    Companies in litigious sectors (telecom, retail, insurance) can track new lawsuits with a minimum-amount filter.
  </Card>

  <Card title="Regulatory follow-up" icon="gavel">
    Watch new lawsuits involving a given regulator or legal grounding.
  </Card>

  <Card title="Sector surveillance" icon="industry">
    Monitor a niche (e.g. class actions in a specific court) without starting from a CPF/CNPJ.
  </Card>
</CardGroup>

Custom tracking allows you to monitor lawsuits using specific filters, returning lawsuits from all courts that match the defined criteria. This query is ideal for identifying lawsuits with specific characteristics across a wide range of jurisdictions.

<Warning>
  For this type of query, make sure to check the pricing, as it is not the same as the historical query.
</Warning>

## Creating a Tracking

To start monitoring with custom filters, you must make a POST request to the `/tracking` route.

### Request Payload

The POST request must include a payload with the following properties:

* `search_type`: This field defines the type of entity to be searched. For custom tracking, it will always have the value `custom`;

* `search_key`: This field defines the value of the entity to be searched. For custom tracking, it will always have the value `custom`;

* `cache_ttl_in_days` (optional): Integer that defines how many days the search result can be considered a valid cache;

* `search_params`: An object containing some search parameters such as:

  * `lawsuit_instance` (optional): This parameter allows you to define the instance in which you want to search the lawsuit;
  * `masked_response`: Defines whether the response will be returned minified. This parameter is only applicable to queries (simple or complete) in the lawsuit search context.
    * `masked_response = true`: will return a complete query
    * `masked_response = false`: will return a simple query

  `*Note` Check the commercial conditions for these different types of custom tracking.

Filters can be added to the request, allowing for a more accurate return based on the desired values. To do this, the `filter` parameter must be included within `search_params`, with the following filters available:

* `filter` (optional): An object containing the search filters, such as:

  * `side` (optional): Allows searching by types of parties in the lawsuit, which can be: `Passive`, `Active`, `Interested`, `Unknown`;

  * `amount_gte` (optional): Filters lawsuits with a case amount greater than or equal to the value specified in `amount_gte`;

  * `amount_lte` (optional): Filters lawsuits with a case amount less than or equal to the value specified in `amount_lte`;

  * `tribunals` (optional): An object containing the court filters:
    * `keys` (optional): List of court codes available in the [list of courts](/en/resource/glossary#lista-de-tribunais). This filter allows you to restrict the search to lawsuits that have or do not have these specific codes;
    * `not_equal` (optional): Boolean value that defines whether the filter will include or exclude the values specified in `keys`.

  * `subject_codes` (optional): An object containing the subject filters:
    * `contains` (optional): List of subject codes. Restricts the search to lawsuits that include the specified codes.
    * `not_contains` (optional): List of subject codes. Excludes lawsuits containing the specified codes.

  * `classification_codes` (optional): An object containing the procedural class filters:
    * `keys` (optional): List of procedural class codes. This filter allows you to restrict the search to lawsuits that have or do not have these specific codes;
    * `not_equal` (optional): Boolean value that defines whether the filter will include or exclude the values specified in `keys`.

  * `credential` (optional): Object for using the credentials vault:
    * `customer_key` (optional): Allows you to pass the user key registered in the credentials vault. If not provided, the API will try to find a credential registered for an empty `customer_key`.

  * `last_step_date_gte` (optional): Restricts the search to lawsuits whose last step date is greater than the provided date.

  * `last_step_date_lte` (optional): Restricts the search to lawsuits whose last step date is less than the provided date.

  * `party_names` (optional): List of names that restricts the search to lawsuits containing them in any of the parties.

    `Note` When using this filter together with the `Side` filter, the `Side` filter will not be considered for restricting these parties, since the `Side` filter is used to filter lawsuits where the main party being searched is on the specified side.

  * `party_documents` (optional): List of documents that restricts the search to lawsuits containing them in any of the parties.

    `Note` When using this filter together with the `Side` filter, the `Side` filter will not be considered for restricting these documents, since the `Side` filter is used to filter lawsuits where the main party being searched is on the specified side.

<Note>
  All registered custom trackings are performed ***on-demand***. We recommend checking the cost conditions associated with this service before using it.
</Note>

```bash theme={null}
curl --location 'https://tracking.production.judit.io/tracking' \
--header 'api-key: <API-KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "recurrence": 2,
    "search": {
        "search_type": "custom",
        "search_key": "",
        "search_params": {
            "filter": {
                "subject_codes": {
                    "contains": [
                        "5953",
                        "6017",
                        "10394",
                        "12989",
                        "5951",
                        "5971",
                        "14",
                        "030213"
                    ]
                },
                "classification_codes": {
                    "keys": [
                        "1116",
                        "12785"
                    ],
                    "not_equal": false
                },
                "party_documents": [
                    "99.999.999/0009-99",
                    "88.888.888/0008-88"
                ]
            }
        }
    }
}'
```

<Note>
  The tracking will be started for the first time within the best court-request
  concurrency window, within the next 24 hours from the creation date.
</Note>

After that, it will run according to the frequency registered in the ***recurrence*** field.

<Accordion title="See response example">
  ```json theme={null}
  {
      "tracking_id": "72084866-499f-4aff-b28a-14d43b8b7d70",
      "user_id": "7f8065a3-4891-428d-9456-dedfc12ff850",
      "status": "created",
      "recurrence": 2,
      "search": {
          "search_type": "custom",
          "search_key": "custom",
          "response_type": "lawsuit",
          "search_params": {
              "filter": {
                  "distribution_date_gte": "2025-02-04T16:56:39.158Z",
                  "subject_codes": {
                      "contains": [
                          "5953",
                          "6017",
                          "10394",
                          "12989",
                          "5951",
                          "5971",
                          "14",
                          "030213"
                      ],
                      "not_contains": []
                  },
                  "classification_codes": {
                      "keys": [
                          "1116",
                          "12785"
                      ],
                      "not_equal": false
                  },
                  "party_names": [],
                  "party_documents": [
                      "99.999.999/0009-99",
                      "88.888.888/0008-88"
                  ]
              },
              "pagination": {}
          }
      },
      "tracked_items_count": 0,
      "tracked_items_steps_count": 0,
      "tags": {},
      "created_at": "2025-02-04T16:56:39.158Z",
      "updated_at": "2025-02-04T16:56:39.158Z"
  }
  ```
</Accordion>

<Note>
  In the tracking creation response, the `hour_range` field is returned, indicating the time at which the court query will be performed for the first time.
</Note>

## Listing Your Trackings

To list all your trackings, you can make a GET request to the `/tracking` route. This route accepts some optional query parameters to paginate and filter the results:

`page`: Defines the page of results you want to retrieve.

`page_size`: Defines the maximum number of results you want to receive per page;

`search_type`: Returns trackings of the specified reference type — use **"custom"** to filter only custom trackings;

`search_key`: Returns trackings with the search related to the value provided;

`status`: Returns trackings whose status can be `created`, `updating`, `updated`, `paused` or `deleted`, or multiple statuses `['updating', 'paused']`;

Here is an example of how to list your trackings using curl:

```bash theme={null}
curl -X GET "https://tracking.production.judit.io/tracking?page=1&page_size=10&search_type=custom" \
-H "api-key: YOUR_API_KEY"
```

## Checking the Tracking Status

The URL takes the **tracking\_id** returned when the tracking was created:

```bash theme={null}
curl --request GET \
--url "https://tracking.production.judit.io/tracking/72084866-499f-4aff-b28a-14d43b8b7d70" \
--header "api-key: YOUR-API-KEY" \
--header "Content-Type: application/json"
```

<Accordion title="See response example">
  ```json theme={null}
  {
      "tracking_id": "72084866-499f-4aff-b28a-14d43b8b7d70",
      "user_id": "7f8065a3-4891-428d-9456-dedfc12ff850",
      "status": "created",
      "recurrence": 2,
      "search": {
          "search_type": "custom",
          "search_key": "custom",
          "response_type": "lawsuit",
          "search_params": {
              "filter": {
                  "distribution_date_gte": "2025-02-04T16:56:39.158Z",
                  "subject_codes": {
                      "contains": [
                          "5953",
                          "6017",
                          "10394",
                          "12989",
                          "5951",
                          "5971",
                          "14",
                          "030213"
                      ],
                      "not_contains": []
                  },
                  "classification_codes": {
                      "keys": [
                          "1116",
                          "12785"
                      ],
                      "not_equal": false
                  },
                  "party_names": [],
                  "party_documents": [
                      "99.999.999/0009-99",
                      "88.888.888/0008-88"
                  ]
              },
              "pagination": {}
          }
      },
      "tracked_items_count": 0,
      "tracked_items_steps_count": 0,
      "tags": {
          "dashboard_id": null
      },
      "request_id": "05ee9825-b2b4-480b-b29e-f071ca7d9c72",
      "created_at": "2025-02-04T16:56:39.158Z",
      "updated_at": "2025-02-04T16:56:39.158Z"
  }
  ```
</Accordion>

The `status` property indicates the current state of the tracking, which can be:

<ol type="a">
  <li>
    <strong>created</strong>: Tracking created, but never executed.
  </li>

  <li>
    <strong>updating</strong>: Has a request currently being processed.
  </li>

  <li>
    <strong>updated</strong>: Tracking updated with at least one response
    available. The <u>updated\_at</u> field indicates the last update date of
    the tracking, and the <u>request\_id</u> property indicates the ID of the
    last request made by the tracking.
  </li>

  <li>
    <strong>paused</strong>: Tracking paused, but can still be resumed.
  </li>

  <li>
    <strong>deleted</strong>: Tracking canceled and can no longer be resumed.
  </li>
</ol>

The **request\_id** property is only created after the tracking has executed for the first time, that is, once it reaches the `updated` status.

## Updating a Tracking

To update a tracking, you can make a PATCH request to the `/tracking/{tracking}` route, replacing `{tracking}` with the ID of the tracking you want to update.

This route accepts optional fields for updating the tracking: `recurrence`, `tags` and the `search` object, with the exception of some fields.

Here is an example of how to do this using curl:

```bash theme={null}
curl -X PATCH "https://tracking.production.judit.io/tracking/{tracking}" \
-H "api-key: YOUR_API_KEY" \
-d '{
  "recurrence": 5,
  "search": {
    "search_type": "custom",
    "search_key": "custom",
    "search_params": {
      "filter": {
        "classification_codes": {
          "keys": ["1116"],
          "not_equal": false
        }
      }
    }
  }
}'
```

## Pausing a Tracking

To pause a tracking, you can make a POST request to the `/tracking/{tracking}/pause` route, replacing `{tracking}` with the ID of the tracking you want to pause.

Here is an example of how to pause a tracking using curl:

```bash theme={null}
curl -X POST "https://tracking.production.judit.io/tracking/72084866-499f-4aff-b28a-14d43b8b7d70/pause" \
-H "api-key: YOUR_API_KEY"
```

Here is an example of the paused tracking response:

```json theme={null}
{
    "tracking_id": "72084866-499f-4aff-b28a-14d43b8b7d70",
    "user_id": "7f8065a3-4891-428d-9456-dedfc12ff850",
    "status": "paused",
    "recurrence": 2,
    "search": {
        "search_type": "custom",
        "search_key": "custom",
        "response_type": "lawsuit",
        "search_params": {
            "filter": {
                "distribution_date_gte": "2025-02-04T16:56:39.158Z",
                "subject_codes": {
                    "contains": [
                        "5953",
                        "6017",
                        "10394",
                        "12989",
                        "5951",
                        "5971",
                        "14",
                        "030213"
                    ],
                    "not_contains": []
                },
                "classification_codes": {
                    "keys": [
                        "1116",
                        "12785"
                    ],
                    "not_equal": false
                },
                "party_names": [],
                "party_documents": [
                    "99.999.999/0009-99",
                    "88.888.888/0008-88"
                ]
            },
            "pagination": {}
        }
    },
    "tracked_items_count": 0,
    "tracked_items_steps_count": 0,
    "tags": {},
    "created_at": "2025-02-04T16:56:39.158Z",
    "updated_at": "2025-02-04T16:56:39.158Z"
}
```

## Resuming a Tracking

To resume a paused tracking, you can make a POST request to the `/tracking/{tracking}/resume` route, replacing `{tracking}` with the ID of the tracking you want to resume.

Here is an example of how to resume a tracking using curl:

```bash theme={null}
curl -X POST "https://tracking.production.judit.io/tracking/72084866-499f-4aff-b28a-14d43b8b7d70/resume" \
-H "api-key: YOUR_API_KEY"
```

Here is an example of an **active** tracking response:

```json theme={null}
{
    "tracking_id": "72084866-499f-4aff-b28a-14d43b8b7d70",
    "user_id": "7f8065a3-4891-428d-9456-dedfc12ff850",
    "status": "updated",
    "recurrence": 2,
    "search": {
        "search_type": "custom",
        "search_key": "custom",
        "response_type": "lawsuit",
        "search_params": {
            "filter": {
                "distribution_date_gte": "2025-02-04T16:56:39.158Z",
                "subject_codes": {
                    "contains": [
                        "5953",
                        "6017",
                        "10394",
                        "12989",
                        "5951",
                        "5971",
                        "14",
                        "030213"
                    ],
                    "not_contains": []
                },
                "classification_codes": {
                    "keys": [
                        "1116",
                        "12785"
                    ],
                    "not_equal": false
                },
                "party_names": [],
                "party_documents": [
                    "99.999.999/0009-99",
                    "88.888.888/0008-88"
                ]
            },
            "pagination": {}
        }
    },
    "tracked_items_count": 0,
    "tracked_items_steps_count": 0,
    "tags": {},
    "created_at": "2025-02-04T16:56:39.158Z",
    "updated_at": "2025-02-04T16:56:39.158Z"
}
```

## Deleting a Tracking

To delete a tracking, you can make a DELETE request to the `/tracking/{tracking}` route, replacing `{tracking}` with the ID of the tracking you want to delete.

<Warning>
  Deletion is **permanent**: the tracker stops running immediately, its future executions are canceled, and the history of responses linked to it remains queryable only via `GET /responses` with the old `origin_id`. If you only want to suspend it temporarily, use [Pause](#pausing-a-tracking) and then [Resume](#resuming-a-tracking).
</Warning>

Here is an example of how to delete a tracking using curl:

```bash theme={null}
curl -X DELETE "https://tracking.production.judit.io/tracking/72084866-499f-4aff-b28a-14d43b8b7d70" \
-H "api-key: YOUR_API_KEY"
```

Here is an example of the deleted tracking response:

```json theme={null}
{
    "tracking_id": "72084866-499f-4aff-b28a-14d43b8b7d70",
    "user_id": "7f8065a3-4891-428d-9456-dedfc12ff850",
    "status": "deleted",
    "recurrence": 2,
    "search": {
        "search_type": "custom",
        "search_key": "custom",
        "response_type": "lawsuit",
        "search_params": {
            "filter": {
                "distribution_date_gte": "2025-02-04T16:56:39.158Z",
                "subject_codes": {
                    "contains": [
                        "5953",
                        "6017",
                        "10394",
                        "12989",
                        "5951",
                        "5971",
                        "14",
                        "030213"
                    ],
                    "not_contains": []
                },
                "classification_codes": {
                    "keys": [
                        "1116",
                        "12785"
                    ],
                    "not_equal": false
                },
                "party_names": [],
                "party_documents": [
                    "99.999.999/0009-99",
                    "88.888.888/0008-88"
                ]
            },
            "pagination": {}
        }
    },
    "tracked_items_count": 0,
    "tracked_items_steps_count": 0,
    "tags": {},
    "created_at": "2025-02-04T16:56:39.158Z",
    "updated_at": "2025-02-04T16:56:39.158Z"
}
```

## Querying the monitoring response via polling

### Request example (GET)

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://requests.production.judit.io/responses?page_size=100&request_id=<request_id>' \
    --header 'api-key: '"$JUDIT_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(
    `https://requests.production.judit.io/responses?page_size=100&request_id=${requestId}`,
    { headers: { "api-key": process.env.JUDIT_API_KEY } }
  );
  const data = await res.json();
  console.log(data.page_data);
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://requests.production.judit.io/responses?page_size=100&request_id=' . urlencode($requestId));
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => ['api-key: ' . getenv('JUDIT_API_KEY')],
  ]);
  echo curl_exec($ch);
  ```

  ```python Python theme={null}
  import os, requests

  resp = requests.get(
      "https://requests.production.judit.io/responses",
      params={"request_id": request_id, "page_size": 100},
      headers={"api-key": os.environ["JUDIT_API_KEY"]},
      timeout=15,
  )
  print(resp.json())
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "io"
      "net/http"
      "net/url"
      "os"
  )

  func main() {
      requestID := "<request_id>"
      base, _ := url.Parse("https://requests.production.judit.io/responses")
      q := base.Query(); q.Set("request_id", requestID); q.Set("page_size", "100")
      base.RawQuery = q.Encode()
      req, _ := http.NewRequest("GET", base.String(), nil)
      req.Header.Set("api-key", os.Getenv("JUDIT_API_KEY"))
      res, _ := http.DefaultClient.Do(req)
      defer res.Body.Close()
      out, _ := io.ReadAll(res.Body); fmt.Println(string(out))
  }
  ```
</CodeGroup>

### Response examples

<Accordion title="See response example — multiple lawsuits detected (200 OK)">
  ```json theme={null}
  {
      "request_status": "completed",
      "page": 1,
      "page_count": 1,
      "all_pages_count": 1,
      "all_count": 2,
      "page_data": [
          {
              "request_id": "8534hyt6-71d5-48a7-a8f1-ad61b02ff461",
              "response_id": "26098ui81f-e0ed-4d41-8f43-4c548d8799bb",
              "origin": "tracking",
              "origin_id": "72084866-499f-4aff-b28a-14d43b8b7d70",
              "response_type": "lawsuit",
              "response_data": {
                  "amount": 17456.15,
                  "attachments": [],
                  "classifications": [
                      {
                          "code": "1116",
                          "name": "EXECUÇÃO FISCAL"
                      }
                  ],
                  "code": "6666666-66.2025.8.19.0001",
                  "county": "CAPITAL 12 VARA FAZ PUBLICA",
                  "city": "RIO DE JANEIRO",
                  "state": "RJ",
                  "justice_description": "JUSTIÇA ESTADUAL",
                  "created_at": "2025-01-27T16:09:19.112Z",
                  "updated_at": "2025-02-04T13:41:08.013Z",
                  "distribution_date": "2025-01-24T17:08:03.000Z",
                  "free_justice": false,
                  "instance": 1,
                  "justice": "8",
                  "last_step": {
                      "lawsuit_cnj": "6666666-66.2025.8.19.0001",
                      "lawsuit_instance": 1,
                      "private": false,
                      "step_id": "5d93c333",
                      "step_date": "2025-01-27T10:30:20.000Z",
                      "content": "Expedição de Carta pelo Correio - 1 carta",
                      "steps_count": 1
                  },
                  "name": "EXAMPLE USER 1 X EXAMPLE USER 2",
                  "parties": [
                      {
                          "side": "Active",
                          "name": "EXAMPLE USER 1",
                          "main_document": "99999999999999",
                          "person_type": "EXEQUENTE",
                          "entity_type": "company",
                          "documents": [
                              {
                                  "document": "99999999999999",
                                  "document_type": "CNPJ"
                              }
                          ],
                          "lawyers": []
                      },
                      {
                          "side": "Passive",
                          "name": "EXAMPLE USER 2",
                          "main_document": "99999999999",
                          "person_type": "EXECUTADO",
                          "entity_type": "company",
                          "documents": [
                              {
                                  "document": "99999999999",
                                  "document_type": "CPF"
                              }
                          ],
                          "lawyers": []
                      }
                  ],
                  "related_lawsuits": [],
                  "secrecy_level": 0,
                  "steps": [],
                  "subjects": [
                      {
                          "code": "6017",
                          "name": "DÍVIDA ATIVA (EXECUÇÃO FISCAL)"
                      },
                      {
                          "code": "5953",
                          "name": "IPVA - IMPOSTO SOBRE PROPRIEDADE DE VEÍCULOS AUTOMOTORES"
                      }
                  ],
                  "tribunal": "19",
                  "tribunal_acronym": "TJRJ"
              },
              "user_id": "7f8065a3-4891-428d-9456-dedfc12ff850",
              "created_at": "2025-02-04T13:41:01.175Z",
              "tags": {
                  "dashboard_id": null
              }
          },
          {
              "request_id": "85347a1e-71d5-48a7-a8f1-ad61b02ff461",
              "response_id": "2ddaf881-d0be-42bb-9ae9-74d76447e1b2",
              "origin": "tracking",
              "origin_id": "72084866-499f-4aff-b28a-14d43b8b7d70",
              "response_type": "lawsuit",
              "response_data": {
                  "amount": 13687.36,
                  "attachments": [],
                  "classifications": [
                      {
                          "code": "1116",
                          "name": "EXECUÇÃO FISCAL"
                      }
                  ],
                  "code": "3000133-12.2025.8.19.0001",
                  "county": "CAPITAL 11 VARA FAZ PUBLICA",
                  "city": "RIO DE JANEIRO",
                  "state": "RJ",
                  "justice_description": "JUSTIÇA ESTADUAL",
                  "created_at": "2025-01-23T16:09:20.134Z",
                  "updated_at": "2025-02-04T13:41:06.691Z",
                  "distribution_date": "2025-01-22T15:19:46.000Z",
                  "free_justice": false,
                  "instance": 1,
                  "justice": "8",
                  "last_step": {
                      "lawsuit_cnj": "3000133-12.2025.8.19.0001",
                      "lawsuit_instance": 1,
                      "private": false,
                      "step_id": "7db05f9a",
                      "step_date": "2025-01-29T03:48:25.000Z",
                      "content": "Confirmada a intimação eletrônica",
                      "steps_count": 7
                  },
                  "name": "EXAMPLE USER 3 X EXAMPLE USER 4",
                  "parties": [
                      {
                          "side": "Active",
                          "name": "EXAMPLE USER 3",
                          "main_document": "99999999999999",
                          "person_type": "EXEQUENTE",
                          "entity_type": "company",
                          "documents": [
                              {
                                  "document": "99999999999999",
                                  "document_type": "CNPJ"
                              }
                          ],
                          "lawyers": []
                      },
                      {
                          "side": "Passive",
                          "name": "EXAMPLE USER 4",
                          "main_document": "99999999999",
                          "person_type": "EXECUTADO",
                          "entity_type": "company",
                          "documents": [
                              {
                                  "document": "99999999999",
                                  "document_type": "CPF"
                              }
                          ],
                          "lawyers": []
                      }
                  ],
                  "related_lawsuits": [],
                  "secrecy_level": 0,
                  "steps": [],
                  "subjects": [
                      {
                          "code": "6017",
                          "name": "DÍVIDA ATIVA (EXECUÇÃO FISCAL)"
                      }
                  ],
                  "tribunal": "19",
                  "tribunal_acronym": "TJRJ"
              },
              "user_id": "7f8065a3-4891-428d-9456-dedfc12ff850",
              "created_at": "2025-02-04T13:41:01.175Z",
              "tags": {
                  "dashboard_id": null
              }
          }
      ]
  }
  ```
</Accordion>

## Receiving the response via webhook

<Info>
  👉 *[Learn how to configure and receive Webhooks here](/en/webhook/callbacks)*
</Info>

**Note**: Each new lawsuit distributed that matches the custom tracking filters will be notified via webhook containing the full lawsuit data.

<Accordion title="See response example">
  ```json theme={null}
  {
    "_id": {
      "$oid": "65f0efe046ad3bda5b27be2d"
    },
    "callback_id": "be1406d9-d62d-402d-8e0e-8684044645de",
    "event_type": "response_created",
    "reference_type": "tracking",
    "reference_id": "72084866-499f-4aff-b28a-14d43b8b7d70",
    "user_id": "7f8065a3-4891-428d-9456-dedfc12ff850",
    "webhook_id": "2f82201d-1439-436d-8c6a-2e6b3e36a54f",
    "payload": {
      "request_id": "7d50b66c-3e86-4d0b-95af-5ff7561d18ff",
      "response_id": "12576767-d3ea-4ea2-8805-6f2a73ef3439",
      "response_type": "lawsuit",
      "response_data": {
        "code": "6666666-66.2025.8.19.0001",
        "justice": "8",
        "tribunal": "19",
        "tribunal_acronym": "TJRJ",
        "instance": 1,
        "distribution_date": "2025-01-24T17:08:03.000Z",
        "secrecy_level": 0,
        "subjects": [
          {
            "code": "6017",
            "name": "DÍVIDA ATIVA (EXECUÇÃO FISCAL)"
          }
        ],
        "classifications": [
          {
            "code": "1116",
            "name": "EXECUÇÃO FISCAL"
          }
        ],
        "parties": [
          {
            "side": "Active",
            "name": "EXAMPLE USER 1",
            "main_document": "99999999999999",
            "person_type": "EXEQUENTE",
            "documents": [
              {
                "document": "99999999999999",
                "document_type": "CNPJ"
              }
            ],
            "lawyers": []
          },
          {
            "side": "Passive",
            "name": "EXAMPLE USER 2",
            "main_document": "99999999999",
            "person_type": "EXECUTADO",
            "documents": [
              {
                "document": "99999999999",
                "document_type": "CPF"
              }
            ],
            "lawyers": []
          }
        ],
        "attachments": [],
        "steps": [],
        "amount": 17456.15,
        "state": "RJ",
        "city": "RIO DE JANEIRO",
        "justice_description": "JUSTIÇA ESTADUAL"
      }
    }
  }
  ```
</Accordion>

<Warning>
  To register your webhook, contact the [support](https://api.whatsapp.com/send/?phone=5521976748865) team and request its creation. Alternatively, the webhook can also be specified by adding the `callback_url` parameter to the request payload, as shown in the example below:
</Warning>

```json theme={null}
{
    "recurrence": 2,
    "search": {
        "search_type": "custom",
        "search_key": "custom",
        "search_params": {
            "filter": {
                "classification_codes": {
                    "keys": ["1116"],
                    "not_equal": false
                }
            }
        }
    },
    "callback_url": "https://webhook.site/b0ac6522-5bfc-42fa-bebf-a8c2b5ec0999",
    "notification_emails": ["example@example.com"]
}
```

## Checking Tracking Information

To retrieve all information about a specific tracking, you can make a GET request to the `/tracking` route, passing the `tracking_id` as a query parameter.

Here is an example of how to do this using curl:

```bash theme={null}
curl -X GET "https://tracking.production.judit.io/tracking?tracking_id=72084866-499f-4aff-b28a-14d43b8b7d70" \
-H "api-key: YOUR_API_KEY"
```

Here is the expected response:

```json theme={null}
{
    "tracking_id": "72084866-499f-4aff-b28a-14d43b8b7d70",
    "user_id": "7f8065a3-4891-428d-9456-dedfc12ff850",
    "status": "updated",
    "recurrence": 2,
    "search": {
        "search_type": "custom",
        "search_key": "custom",
        "response_type": "lawsuit",
        "search_params": {
            "filter": {
                "distribution_date_gte": "2025-02-04T16:56:39.158Z",
                "subject_codes": {
                    "contains": [
                        "5953",
                        "6017",
                        "10394",
                        "12989",
                        "5951",
                        "5971",
                        "14",
                        "030213"
                    ],
                    "not_contains": []
                },
                "classification_codes": {
                    "keys": [
                        "1116",
                        "12785"
                    ],
                    "not_equal": false
                },
                "party_names": [],
                "party_documents": [
                    "99.999.999/0009-99",
                    "88.888.888/0008-88"
                ]
            },
            "pagination": {}
        }
    },
    "tracked_items_count": 0,
    "tracked_items_steps_count": 0,
    "tags": {},
    "created_at": "2025-02-04T16:56:39.158Z",
    "updated_at": "2025-02-04T16:56:39.158Z"
}
```

## Tracking History

To retrieve the history of responses generated by a specific tracking, make a GET request to the `/responses/tracking/{tracking}` route, replacing `{tracking}` with the desired tracking ID.

You can filter the results using the `created_at_gte` and `created_at_lte` parameters, where:

`created_at_gte`: defines the start date of the query.
`created_at_lte`: defines the end date of the query.

Here is an example of how to do this using curl:

```bash theme={null}
curl --location 'https://requests.production.judit.io/responses/tracking/<TRACKING_ID>?order=asc&page=1&page_size=50&created_at_gte=2024-03-05T00%3A00%3A00&created_at_lte=2025-03-11T00%3A00%3A00' \
--header 'api-key: <API-KEY>'
```

Here is the expected response:

<Accordion title="See response example">
  ```json theme={null}
  {
      "request_status": "completed",
      "page": 1,
      "page_count": 2,
      "all_pages_count": 1,
      "all_count": 2,
      "page_data": [
          {
              "request_id": "644a4759-1ae2-48a4-8b09-76afffc75849393",
              "response_id": "a37ca823-e1d2-4de4-a973-ec9e859d21ed",
              "origin": "tracking",
              "origin_id": "72084866-499f-4aff-b28a-14d43b8b7d70",
              "response_type": "lawsuit",
              "response_data": {
                  "amount": 13687.36,
                  "attachments": [],
                  "classifications": [
                      {
                          "code": "1116",
                          "name": "EXECUÇÃO FISCAL"
                      }
                  ],
                  "code": "3000133-12.2025.8.19.0001",
                  "county": "TESTE TRIBUNAL",
                  "city": "RIO DE JANEIRO",
                  "state": "RJ",
                  "justice_description": "JUSTIÇA ESTADUAL",
                  "created_at": "2025-01-23T16:09:20.134Z",
                  "updated_at": "2025-01-24T16:10:56.948Z",
                  "distribution_date": "2025-01-22T15:19:46.000Z",
                  "free_justice": false,
                  "instance": 1,
                  "justice": "8",
                  "last_step": {
                      "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                      "lawsuit_instance": 1,
                      "private": false,
                      "step_id": "91dc5544",
                      "step_date": "2025-01-22T18:40:18.000Z",
                      "content": "Conclusos para decisão/despacho",
                      "steps_count": 1
                  },
                  "name": "EXAMPLE USER 1 X EXAMPLE USER 2",
                  "parties": [
                      {
                          "side": "Active",
                          "name": "EXAMPLE USER 1",
                          "main_document": "99999999999999",
                          "person_type": "EXEQUENTE",
                          "entity_type": "company",
                          "documents": [
                              {
                                  "document": "99999999999999",
                                  "document_type": "CNPJ"
                              }
                          ],
                          "lawyers": []
                      },
                      {
                          "side": "Passive",
                          "name": "EXAMPLE USER 2",
                          "main_document": "99999999999",
                          "person_type": "EXECUTADO",
                          "entity_type": "company",
                          "documents": [
                              {
                                  "document": "99999999999999",
                                  "document_type": "CNPJ"
                              }
                          ],
                          "lawyers": []
                      }
                  ],
                  "related_lawsuits": [],
                  "secrecy_level": 0,
                  "steps": [],
                  "subjects": [
                      {
                          "code": "6017",
                          "name": "DÍVIDA ATIVA (EXECUÇÃO FISCAL)"
                      },
                      {
                          "code": "5953",
                          "name": "IPVA - IMPOSTO SOBRE PROPRIEDADE DE VEÍCULOS AUTOMOTORES"
                      }
                  ],
                  "tribunal": "19",
                  "tribunal_acronym": "TJRJ"
              },
              "user_id": "7f8065a3-4891-428d-9456-dedfc12ff850",
              "created_at": "2025-01-24T16:10:53.278Z",
              "tags": {
                  "dashboard_id": null
              }
          },
          {
              "request_id": "32e0cbb6-71ed-4165-81d5-08ef4dcf80c6",
              "response_id": "a6690acb-0856-4e4d-ae69-c8d808ce7d9e",
              "origin": "tracking",
              "origin_id": "72084866-499f-4aff-b28a-14d43b8b7d70",
              "response_type": "lawsuit",
              "response_data": {
                  "amount": 17456.15,
                  "attachments": [],
                  "classifications": [
                      {
                          "code": "1116",
                          "name": "EXECUÇÃO FISCAL"
                      }
                  ],
                  "code": "3000233-64.2025.8.19.0001",
                  "county": "CAPITAL 12 VARA FAZ PUBLICA",
                  "city": "RIO DE JANEIRO",
                  "state": "RJ",
                  "justice_description": "JUSTIÇA ESTADUAL",
                  "created_at": "2025-01-27T16:09:19.112Z",
                  "updated_at": "2025-01-27T16:09:19.112Z",
                  "distribution_date": "2025-01-24T17:08:03.000Z",
                  "free_justice": false,
                  "instance": 1,
                  "justice": "8",
                  "last_step": {
                      "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                      "lawsuit_instance": 1,
                      "private": false,
                      "step_id": "5d93c333",
                      "step_date": "2025-01-27T10:30:20.000Z",
                      "content": "Expedição de Carta pelo Correio - 1 carta",
                      "steps_count": 1
                  },
                  "name": "EXAMPLE USER 3 X EXAMPLE USER 4",
                  "parties": [
                      {
                          "side": "Active",
                          "name": "EXAMPLE USER 3",
                          "main_document": "99999999999999",
                          "person_type": "EXEQUENTE",
                          "entity_type": "company",
                          "documents": [
                              {
                                  "document": "99999999999999",
                                  "document_type": "CNPJ"
                              }
                          ],
                          "lawyers": []
                      },
                      {
                          "side": "Passive",
                          "name": "EXAMPLE USER 4",
                          "main_document": "99999999999999",
                          "person_type": "EXECUTADO",
                          "entity_type": "company",
                          "documents": [
                              {
                                  "document": "99999999999999",
                                  "document_type": "CNPJ"
                              }
                          ],
                          "lawyers": []
                      }
                  ],
                  "related_lawsuits": [],
                  "secrecy_level": 0,
                  "steps": [],
                  "subjects": [
                      {
                          "code": "6017",
                          "name": "DÍVIDA ATIVA (EXECUÇÃO FISCAL)"
                      },
                      {
                          "code": "5953",
                          "name": "IPVA - IMPOSTO SOBRE PROPRIEDADE DE VEÍCULOS AUTOMOTORES"
                      }
                  ],
                  "tribunal": "19",
                  "tribunal_acronym": "TJRJ"
              },
              "user_id": "7f8065a3-4891-428d-9456-dedfc12ff850",
              "created_at": "2025-01-27T16:09:18.752Z",
              "tags": {
                  "dashboard_id": null
              }
          }
      ]
  }
  ```
</Accordion>
