Court Case Watch API
Keep following the pending cases of a court records report for 12 months, and hear about each new hearing date, change and disposal.
The documentation opens in the VerifyAll dashboard after sign-in, for accounts with approved API access. New to the API? Start with the developer guide.
Overview
What the Court Case Watch API does
The Court Case Watch API follows the pending cases found by a completed court records report. Switch it on for some or all of a report’s pending cases and VerifyAll checks each watched case on a schedule for 12 months, records each next hearing date and change it finds, and reminds you before hearings.
It is for teams whose decision does not end with the report: a lender with a borrower in a recovery suit, a legal team following a vendor dispute. Instead of re-running searches, you receive webhook events: legal_case.updated for a hearing, a disposal or another change, legal_case.hearing_reminder before a hearing, and legal_case.watch_changed when a watch starts, stops, pauses, renews or ends.
Case watch runs only on the Production key, because every watch is a live, paid one. It is charged as a yearly fee per case, debited from your prepaid wallet when you switch a case on or renew it, and never renews by itself.
How it works
- 1
Take a completed court records report id and call GET /crime/{id}/watch to see whether its cases can be watched and why any cannot (disposed, or no usable case number).
- 2
Call POST /crime/{id}/watch/offer with the cnrs you want (or none for every pending case) to see the yearly price per case and the total; nothing is charged.
- 3
Switch it on with POST /crime/{id}/watch, sending price_per_case_year and total as shown. If the price changed meanwhile, the answer is 409 price_changed and nothing is charged.
- 4
Follow each case with GET /crime/watches and GET /crime/watches/{watchId}, receive legal_case.* webhook events, and renew with POST /crime/watches/{watchId}/renew when renewal_due is true.
Request and response
Court case watch API endpoints and fields
The main fields; the full reference with every field, error code and a cURL sample is in the dashboard docs.
| Endpoint | What it does |
|---|---|
| GET/crime/{id}/watch | Whether a report’s cases can be watched, their price and state |
| POST/crime/{id}/watch/offer | Price of watching the chosen cases, without starting anything |
| POST/crime/{id}/watch | Switch case watch on for the chosen pending cases |
| DELETE/crime/{id}/watch | Switch case watch off for the chosen cases |
| POST/crime/{id}/watch/renew | Pay for another 12 months of a report’s watches that are due |
| GET/crime/watches | Every watched case, filterable by watching, paused, ended or renewal_due |
| GET/crime/watches/{watchId} | One watched case with its hearing history |
| DELETE/crime/watches/{watchId} | Stop watching one case |
| POST/crime/watches/{watchId}/renew | Renew one watched case for 12 months |
| POST/crime/watches/{watchId}/check | Ask for an extra check of a case with no next hearing date |
| GET/crime/watch-settings | Your reminder lead days, channels and yearly price per case |
Request fields
| Field | What it is |
|---|---|
| id (path)Required | The id of a completed court records report (from POST /crime/create). |
| cnrsOptional | The case numbers (the cnr of each case in the report) to act on. Leave out to act on every case that qualifies. |
| price_per_case_yearOptional | Send the yearly price per case you were shown; if the price has changed, the call is refused with 409 and nothing is charged. |
| totalOptional | Send the total the offer showed for the same cnrs; a different amount is refused with 409, not charged. |
| reminder_lead_daysOptional | PUT /crime/watch-settings: how many days before a hearing the reminder is sent. |
What the answer returns
| Field | What it is |
|---|---|
| watch_id / report_id / cnr | VerifyAll’s id of the watched case, the legal report it belongs to and the case number. |
| status | active, no_date (no next hearing on record), paused_check_failed, ended_disposed, stopped or expired. |
| next_hearing_on / next_check_on | The next hearing date on the case record and the day it is next checked. |
| last_change / last_change_at | What the latest check found, as a sentence, and when. |
| paid_until / renewal_due / can_renew | The last day paid for, and whether the watch is due for renewal now. |
| checks_left_to_ask | How many extra checks you may still ask for on a case with no hearing date in its paid year. |
| watchable / not_watchable_reason | Per case in a report: whether it can be watched, or why not (disposed, no_cnr or not_offered). |
Base URL https://api.verifyall.ai. Authenticate with the X-API-Key header (a va_sandbox_ or va_live_ key). Every answer carries data, status_code, success, message and message_code; checks add outcome, checkResultId, charged and charged_amount.
Key features
Court Case Watch API features and capabilities
Webhook events for every change
legal_case.updated, legal_case.hearing_reminder and legal_case.watch_changed reach your endpoint, signed, so your case system updates itself.
Price confirmed before charge
Start and renew calls carry the price you were shown; if it changed, the call is refused with 409 and nothing is debited.
Choose the cases
Watch every pending case of a report or only the ones that matter, by their case numbers, and stop any one of them at any time.
Ends cleanly
A disposed case ends its watch with a final update; a paid year that is not renewed expires, and nothing renews by itself.
Use cases
Where businesses use the Court Case Watch API
Borrower litigation monitoring
Follow recovery suits and cheque bounce cases against a borrower through the life of the loan.
Vendor dispute tracking
Know before each hearing in a dispute that involves a key supplier or distributor.
Pending case of a hire
Follow a pending case found during screening and act when it is decided.
Legal team calendars
Feed hearing dates and changes into your legal team’s calendar or case management tool by webhook.
Industries
Coverage
Pending cases of a completed court records report on a person or a business that carry a usable case number (CNR), for 12 months per payment.
Limitations to plan for
- Production key only. The Sandbox cannot start a watch, because its sample report carries no case numbers.
- Only pending cases with a usable case number can be watched; disposed cases cannot.
- Stopping a watch does not refund the paid year. Renewal is never automatic.
- Case watch can be unavailable at times (available: false), and alert channels depend on your account settings.
Integration
How to integrate the Court Case Watch API
From a business account to your first live call.
Step 1
Create a business account on VerifyAll and get it approved, as for running checks in the dashboard.
Step 2
Request Developer API access under Developers in the dashboard: the APIs you need, your expected monthly volume and your use case. The VerifyAll team reviews it and shares the API Services Agreement.
Step 3
Once the agreement is signed and access is approved, create your Sandbox key and build against sample data. Sandbox calls are never charged.
Step 4
Create your Production key, recharge your wallet and switch the key in your code: the endpoint and fields stay the same.
Get started
Request access to the Court Case Watch API
Tell us what you want to verify. We reply within one business day with access steps, Sandbox details and your API pricing.
View API documentation
The full reference for Court Case Watch API (endpoints, fields, errors, cURL) opens in the dashboard once your access is approved.
Open the docs (sign-in)Create a business account
API keys are issued to an approved business account. Sign up, then request access under Developers.
Create account
Pricing
Production calls are charged per check from your prepaid VerifyAll wallet, at your account’s API price; GST is added separately when you recharge. Sandbox calls are never charged. Your API prices are shown in the dashboard once access is approved. How pricing works
Already have a business account? Sign in to request access
Court Case Watch API: frequently asked questions
Answers for teams planning an integration.
Still have questions? Our team is happy to help.
Contact SupportRelated APIs
Court Records Verification API
LiveFinishes laterFind the civil and criminal court cases of a person or a business, with each case’s court, status and next hearing, in one asynchronous API.
View API detailsAML Screening API
LiveInstant answerScreen a person or an entity against sanctions, enforcement and regulatory watch lists and adverse media in one call, with every hit scored.
View API detailsBackground Verification API
LiveFinishes laterRun the background checks you choose on one person in a single request, and read back one report with an overall result and every check’s outcome.
View API details
All legal and AML APIsRun Court case watch in the dashboard, without codeBrowse the API Marketplace
Start with the Court Case Watch API
Request access, build against the Sandbox, then go live with your Production key.