Creating the tracking
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. The possible values are:cpf, cnpj, oab, name, lawsuit_cnj or lawsuit_id. For lawsuit searches, we will specifically use cpf, cnpj or oab, which correspond to the lawsuit number.-
search_key: The lawsuit number (CNJ code), CPF, CNPJ, OAB or Name you want to search; -
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_responseDefines whether the response will be returned minified. This parameter is only applicable to queries (simple or complete) by document in the lawsuit search context. - masked_response =true: will return a complete query - masked_response =false: will return a simple query*NoteCheck the commercial conditions for these different types of document-based queries.
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 inamount_gte; -
amount_lte(optional): Filters lawsuits with a case amount less than or equal to the value specified inamount_lte; -
tribunals(optional): An object containing the court filters:keys(optional): List of court codes available in the list of courts. 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 inkeys.
-
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 inkeys.
-
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 emptycustomer_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.NoteWhen using this filter together with theSidefilter, theSidefilter will not be considered for restricting these parties, since theSidefilter 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.NoteWhen using this filter together with theSidefilter, theSidefilter will not be considered for restricting these documents, since theSidefilter is used to filter lawsuits where the main party being searched is on the specified side. -
notification_emails(optional): Array of strings outside ofsearchwhere you can add email addresses to receive notifications for every update of the registered tracking.
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.
All registered new-cases trackings are performed on-demand. We recommend checking the cost conditions associated with this service before using it.
In the tracking creation response, the
hour_range field is returned, indicating the time at which the court queries will be performed for the first time. In the example above, the first query is scheduled to occur at 9 PM.Checking the tracking status
The URL takes the tracking_id returned in the first request:Response:The status property indicates the current state of the tracking, which can be:
- created: Tracking created, but never executed.
- updating: Has a request currently being processed.
- updated: Tracking updated with at least one response available. The updated_at field indicates the last update date of the tracking, and the request_id property indicates the ID of the last request made by the tracking.
- paused: Tracking paused, but can still be resumed.
- deleted: Tracking canceled and can no longer be resumed.
Retrieving the response content (new case found)
The URL takes the request_id returned in the first request:
The page and page_size parameters are optional but necessary to navigate through the pages of lawsuits, in case there is more than one — which is common for searches by document.
The meaning of each field can be found in the glossary
Example request response
Example request response
Pagination properties:
Pagination properties:
Defines the current page of the search.
Total number of lawsuits on the page.
Total number of lawsuits found.
Number of lawsuit pages.
Array with the responses, and within the response_data property, the lawsuit content.
For document-based tracking, it will always be for new cases — that is, requests will only produce responses when a new lawsuit is distributed.
Retrieving the history of a tracking
To retrieve the history of responses generated by a specific tracking, make a GET request to the Here is the expected response:
/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:Pausing a tracking
To pause a tracking, you can make a POST request to the Here is an example of the paused tracking response:
/tracking/{tracking}/pause route, replacing {tracking} with the ID of the tracking you want to pause.Here is an example of how to pause the tracking using curl:Resuming a tracking
To resume a paused tracking, you can make a POST request to the Here is an example of an active tracking response:
/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: