Events

An event is a record that something happened to a case, an order, a watch, a report or a job. Each event is delivered to your webhook endpoints and kept in the event log, so you can also fetch it. The log is free and needs the scope webhooks:write.

#Read the event log

GET /events?after=&type=&limit= returns events, oldest first, 20 at a time by default. Pass the id of the last event you handled, or the next_cursor of the page, as after (or cursor) to get the events that follow. See pagination.

Parameter	Meaning
after	An event id. Only events after it. An id from the other mode, or one a sandbox reset removed, gives 400 invalid_after.
cursor	The next_cursor of the previous page. It is an event id too, so it works as after.
type	Only events of this type.
limit	1 to 100. Default 20.

curl "https://adv.heliosynctech.com/api/v1/events?type=case.next_date_changed&limit=2" \
  -H "Authorization: Bearer $AOS_KEY"

{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "evt_5nQ7xLp2Vt9RkB4mCe8Hy1Ws",
      "type": "case.next_date_changed",
      "mode": "test",
      "created_at": "2026-12-01T10:20:00+05:30",
      "data": {
        "watch_id": "wch_41",
        "cnr": "SBXX010000012026",
        "changes": [ { "field": "next_hearing_date", "from": "2026-12-08", "to": "2026-12-22" } ],
        "case": { "object": "case", "cnr": "SBXX010000012026", "status": "pending", "next_hearing_date": "2026-12-22", "protected": false },
        "sandbox": true
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /events/{id} returns one event (404 event_not_found). Use the log to catch up after your server was down, or to check what a webhook should have sent. The CLI's aos listen reads this log; see the CLI. A live key sees live events and a test key sees test events; they never mix. A test key's call also brings in the news of watched sandbox cases when the sandbox date has moved on; see monitoring.

An event in the log and the same event as a webhook carry the same fields, mode (test or live) among them; see webhooks. Reports, watches and webhook endpoints are different: they carry livemode (true or false).

#Event types

Every event has id (evt_…), object (event), type, mode, created_at and data.

Type	Sent when	data
case.updated	Anything on a watched case changed (next date, status, stage, judge, decision date)	watch_id, cnr, changes, case
case.next_date_changed	The court fixed a new next date	watch_id, cnr, changes, case
case.disposed	The case ended	watch_id, cnr, changes, case
order.published	A new order or judgment is on a watched case	watch_id, cnr, order, case
causelist.listed	A watched case appears on a cause list	watch_id, cnr, date, court, court_no, item_no, case_number, case
party.new_case	A watched person or company is named in a case it was not in before	watch_id, key, name, state, score, why, source, case
report.completed	A report is ready	report
report.failed	A report could not be made. It is free	report
job.completed	An intelligence job finished	job
job.failed	An intelligence job failed. It is free	job
webhook.test	You called POST /webhook-endpoints/{id}/test	message

A case event is sent for each watch on the case. The data stays small on purpose. To get more, call the API with the ids it gives: GET /cases/{cnr}, GET /orders/{id}, GET /reports/{id}, GET /jobs/{id}.

In test mode the same payloads carry "sandbox": true, and case is the sandbox case.

#case.updated, case.next_date_changed, case.disposed

The three share one payload. changes lists what moved since the last read: field is one of next_hearing_date, status, stage, judge or decision_date. A new next date sends both case.updated and case.next_date_changed; a disposal sends case.updated and case.disposed.

{
  "watch_id": "wch_41",
  "cnr": "SBXX010000012026",
  "changes": [ { "field": "next_hearing_date", "from": "2026-12-08", "to": "2026-12-22" } ],
  "case": {
    "object": "case",
    "cnr": "SBXX010000012026",
    "court_name": "Sandbox High Court, South Bench",
    "case_type": "RFA",
    "registration_number": "3964/2026",
    "petitioner": "Fernandes Logistics LLP",
    "respondent": "Reddy Textiles Pvt Ltd",
    "status": "pending",
    "stage": "Admission",
    "judge": "Hon'ble Justice R. Fernandes",
    "next_hearing_date": "2026-12-22",
    "decision_date": null,
    "protected": false
  }
}

A protected case has its party names shown as [name withheld: protected category].

#order.published

{
  "watch_id": "wch_41",
  "cnr": "SBXX010000032026",
  "order": { "object": "order", "id": "ord_4821", "cnr": "SBXX010000032026", "kind": "order", "no": "197", "date": "2026-12-02", "title": "Daily order" },
  "case": { "object": "case", "cnr": "SBXX010000032026", "status": "pending", "next_hearing_date": "2026-12-03", "protected": false }
}

The event is free. Fetch the order with GET /orders/ord_4821; the text costs ₹1.50, see court data. (In the sandbox the id is sbx_SBXX010000032026_197.)

#causelist.listed

{
  "watch_id": "wch_41",
  "cnr": "SBXX010000012026",
  "date": "2026-12-08",
  "court": "Sandbox High Court",
  "court_no": "5",
  "item_no": "1",
  "case_number": "RFA 3964/2026",
  "case": { "object": "case", "cnr": "SBXX010000012026", "status": "pending", "next_hearing_date": "2026-12-08", "protected": false }
}

It is sent once for each watch and list date.

#party.new_case

{
  "watch_id": "wch_42",
  "key": "SBXX010002532026",
  "name": "Sandbox Lender Finance Ltd",
  "state": "Delhi",
  "score": 95,
  "why": ["Named as the petitioner"],
  "source": "cause_list",
  "case": {
    "cnr": "SBXX010002532026",
    "case_number": "RFA 7147/2026",
    "petitioner": "Sandbox Lender Finance Ltd",
    "respondent": "Agarwal Textiles Pvt Ltd",
    "court": "Sandbox High Court, North Bench",
    "court_no": "1",
    "list_date": "2026-12-08"
  }
}

score is how closely the name matches (0 to 100); why says in words. It is sent once for each watch and case. A test party watch sends this only through POST /sandbox/events.

#report.completed and report.failed

report is the report object without its hits: the summary and, for due diligence, the entities are there for a completed report; error.message is there for a failed one.

{
  "report": {
    "object": "report",
    "id": "rpt_3cJ8vNd5Qw2TzXa7Uf4LbYh9",
    "type": "litigation_check",
    "status": "completed",
    "livemode": false,
    "subject": { "kind": "company", "name": "Sandbox Lender Finance Ltd", "father_name": null, "cin": null, "state": "Delhi", "district": null },
    "created_at": "2026-12-01T10:20:00+05:30",
    "completed_at": "2026-12-01T10:20:04+05:30",
    "pdf_url": "https://adv.heliosynctech.com/api/v1/reports/rpt_3cJ8vNd5Qw2TzXa7Uf4LbYh9/pdf",
    "verify_url": "https://adv.heliosynctech.com/verify/K7Q2M9XD",
    "note": null,
    "error": null,
    "summary": { "cases_found": 5, "possible_matches": 0, "by_confidence": { "high": 5, "medium": 0, "low": 0 } }
  }
}

(summary is shortened.) Read the full report, with its hits, from GET /reports/{id}.

#job.completed and job.failed

job is the job object without its result. Read the result from GET /jobs/{id}.

{
  "job": {
    "object": "job",
    "id": "job_7hPz2KmV9aXq4Ld6Rs1TnE8c",
    "kind": "ocr",
    "status": "completed",
    "pages": 42,
    "batch": false,
    "credits": 16.8,
    "created_at": "2026-12-01T10:20:00+05:30",
    "completed_at": "2026-12-01T10:23:10+05:30"
  }
}

A failed job has "status": "failed" and "error": { "message": "…" }.

#webhook.test

{ "message": "A test event from Advocate OS." }

#Order and duplicates

Events are numbered by time, not by arrival. A webhook can arrive twice or late; the log has each event once. Treat id as the key and handle a repeat as a no-op.