Sandbox

A test key (aos_test_…) talks to the Sandbox High Court: a made-up court with made-up cases, so you can build and test without paying, without a real party's data and without hitting a court portal.

#The test rules

• A test call costs 0 credits. It is recorded with mode test and never touches your wallet.
• A test key reads only sandbox court data. Test mode never reaches a court portal, a real person or money.
• Sending a real CNR with a test key returns 400 with the code test_mode_live_cnr. See errors.
• Test keys are allowed 50 requests a second. They have no spend limit, because they spend nothing.
• Research and law endpoints (judgments, acts, citations, limitation) read the real public library, and are free in test mode.
• Intelligence endpoints (OCR, translation, drafts, answers) return fixed sample output marked "sandbox": true. No AI runs.
• Reports in test mode run on sandbox parties only.
• Test webhook endpoints receive test events. Every endpoint, test or live, must be https to a public address; for local work use aos listen.
• Workspace endpoints are the exception to "made-up data": a test key reads your firm's own workspace, free. Its writes are dry runs: checked as live, answered 201 with "sandbox": true and an sbx_ id, and saved nowhere. See workspace.
• Test watches give events when the sandbox date moves on; see monitoring.

#Sandbox CNRs

A sandbox CNR is SBXX01, then six digits, then 2026. It is 16 characters, like a real CNR. Every sandbox case is generated from its CNR, so the same CNR gives the same case every time: Indian names, Sandbox High Court benches, stages, orders with text and cause-list appearances.

CNR	What it does
SBXX010000012026	Pending. The next date is 7 days after the sandbox date.
SBXX010000022026	Disposed, with the final order attached.
SBXX010000032026	A new order every sandbox day. Use it to test a watch and a webhook.
SBXX010000042026	The court portal is down: 503 upstream_unavailable, code portal_unavailable. Not billed.
SBXX010000052026	A protected category: the parties' names are shown as [name withheld: protected category], and its order text is withheld.
SBXX019999992026	Not found: 404 case_not_found. Not billed.

Any other CNR of the form SBXX01 + six digits + 2026 also works and gives a case generated from that number. Use it for volume tests.

#The sandbox date

The sandbox has its own clock. It starts as today (IST). Send the header AOS-Sandbox-Date: yyyy-MM-dd to set it for one call. It drives next dates, cause-list entries, new orders and limitation.

curl https://adv.heliosynctech.com/api/v1/cases/SBXX010000012026 \
  -H "Authorization: Bearer $AOS_KEY" \
  -H "AOS-Sandbox-Date: 2026-12-01"

{ "object": "case", "cnr": "SBXX010000012026", "status": "pending", "next_hearing_date": "2026-12-08", "sandbox": true, "…": "…" }

(The case is shortened; see court data.) Send a later date and the same case moves on: a later next date. Send one date, then the next day, to see SBXX010000032026 get a new order. Cause lists, holidays and limitation follow the same date.

#Search by party

Cause lists and name searches read a fixed pool of sandbox cases: the six CNRs above, minus the portal-down and not-found ones, and the numbers SBXX010001002026 to SBXX010003992026. GET /cases?party=Sandbox Lender returns a fixed set of five, so you can test a litigation check or a name search without a real person. A protected case never answers to a name. Party names in the sandbox are always made up.

#Reset the sandbox

POST /sandbox/reset is free and works with test keys only. It clears your test watches, test event log and test webhook deliveries. Your keys and webhook endpoints stay.

curl -X POST https://adv.heliosynctech.com/api/v1/sandbox/reset -H "Authorization: Bearer $AOS_KEY"

{ "object": "sandbox_reset", "deleted": { "deliveries": 6, "events": 14, "watches": 2 } }

#Send yourself an event

POST /sandbox/events is free and works with test keys only. It puts a test event in your event log and delivers it to your test webhook endpoints, signed like a live one. Send the type (see event types) and, optionally, a sandbox cnr (default SBXX010000032026). The event carries that case, a sample order for order.published, and "sandbox": true. This is also the only way to get party.new_case in test mode.

curl -X POST https://adv.heliosynctech.com/api/v1/sandbox/events \
  -H "Authorization: Bearer $AOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "case.next_date_changed", "cnr": "SBXX010000012026" }'

It answers 201 with the event:

{
  "object": "event",
  "id": "evt_5nQ7xLp2Vt9RkB4mCe8Hy1Ws",
  "type": "case.next_date_changed",
  "mode": "test",
  "created_at": "2026-12-01T10:20:00+05:30",
  "data": { "case": { "object": "case", "cnr": "SBXX010000012026", "status": "pending", "next_hearing_date": "2026-12-08", "…": "…" }, "sandbox": true }
}

#What to test before you go live

1. Your happy path against SBXX010000012026.
2. A disposed case (SBXX010000022026): your code must not wait for another hearing.
3. A masked case (SBXX010000052026): your code must cope with a masked name.
4. A 503 (SBXX010000042026): retry with backoff, and do not charge your own customer for it.
5. A 404 (SBXX019999992026): show "no such case", not an error page.
6. A webhook arriving twice, and out of order. See webhooks.