Advocate OS
Start free
DevelopersDocsStart here

Quickstart

Sign up, make a test key and read your first case from the sandbox High Court in curl, TypeScript, Python or PHP, in under five minutes.

Open in Claude Open in ChatGPT

You will make one real API call, free, against the sandbox. You need nothing installed except what your language already has.

#1. Sign up

Create an account the way any firm does. A developer account is a firm: there is no separate developer sign-up. If you already use Advocate OS, you already have one.

#2. Make a test key

  1. Sign in and open Firm › Developers.
  2. Choose New key, name it (for example "laptop"), pick Test, and choose Make a key.
  3. Copy the key now. It looks like aos_test_ followed by 40 letters and digits. It is shown once; after that only its last four characters are kept.

A test key reads only the sandbox, costs nothing and never touches a court. See sandbox.

#3. Set two environment variables

Never write a host or a key into code. Every SDK, the CLI and the examples read these two.

export AOS_API_BASE="https://adv.heliosynctech.com/api/v1"
export AOS_KEY="aos_test_paste_your_key_here"

#4. Read a case

SBXX010000012026 is a pending sandbox case. Its next date is seven days after the sandbox date.

Bearer aos_test_ or aos_live_ keyJSON, with AOS-Credits-ChargedSigned webhooks when a watched case changesYour appAOS_API_BASE, AOS_KEYAdvocate OS API/api/v1, JSONCourt datacases, cause lists, ordersResearch and lawjudgments, bare acts, limitationIntelligenceOCR, summaries, drafts
How a call works
curl "$AOS_API_BASE/cases/SBXX010000012026" \
  -H "Authorization: Bearer $AOS_KEY"

// Node 18 or newer. Run with: node --experimental-strip-types first-call.ts
const res = await fetch(`${process.env.AOS_API_BASE}/cases/SBXX010000012026`, {
  headers: { Authorization: `Bearer ${process.env.AOS_KEY}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message} (${body.error.doc_url})`);
console.log(body.status, body.next_hearing_date, "charged", res.headers.get("AOS-Credits-Charged"));

# pip install requests
import os, requests

res = requests.get(
    f"{os.environ['AOS_API_BASE']}/cases/SBXX010000012026",
    headers={"Authorization": f"Bearer {os.environ['AOS_KEY']}"},
    timeout=30,
)
body = res.json()
if not res.ok:
    e = body["error"]
    raise SystemExit(f"{e['code']}: {e['message']} ({e['doc_url']})")
print(body["status"], body["next_hearing_date"], "charged", res.headers.get("AOS-Credits-Charged"))

<?php
$ch = curl_init(getenv('AOS_API_BASE') . '/cases/SBXX010000012026');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AOS_KEY')],
    CURLOPT_HEADER => true,
]);
$raw = curl_exec($ch);
$body = json_decode(substr($raw, curl_getinfo($ch, CURLINFO_HEADER_SIZE)), true);
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) >= 400) {
    exit("{$body['error']['code']}: {$body['error']['message']} ({$body['error']['doc_url']})\n");
}
echo "{$body['status']} {$body['next_hearing_date']}\n";

You should get back something like this (the headers are shown first):

HTTP/2 200
AOS-Request-Id: req_8fK2mQx0Zp3LrT7vWc9aB1dE
AOS-Mode: test
AOS-Credits-Charged: 0
RateLimit-Limit: 50
RateLimit-Remaining: 49
RateLimit-Reset: 1

{
  "object": "case",
  "cnr": "SBXX010000012026",
  "court": "SBHC-S",
  "court_name": "Sandbox High Court, South Bench",
  "case_type": "RFA",
  "registration_number": "3964/2026",
  "petitioner": "Fernandes Logistics LLP",
  "respondent": "Reddy Textiles Pvt Ltd",
  "judge": "Hon'ble Justice R. Fernandes",
  "stage": "Admission",
  "status": "pending",
  "next_hearing_date": "2026-12-08",
  "decision_date": null,
  "protected": false,
  "sandbox": true,
  "orders": [ "…" ]
}

The case is shortened here; the whole object is in court data. The values change with the sandbox date.

AOS-Credits-Charged: 0 is what a test key always shows. The sandbox date is today unless you send AOS-Sandbox-Date: yyyy-MM-dd; try AOS-Sandbox-Date: 2027-01-01 and watch the next date move.

#5. Break it on purpose

Ask for a case that does not exist:

curl -i "$AOS_API_BASE/cases/SBXX019999992026" -H "Authorization: Bearer $AOS_KEY"

You get a 404 with the error type not_found and the code case_not_found, and its doc_url opens the page that says how to fix it. Errors and the sandbox cases that cause them are covered in errors and sandbox.

#6. Go live

  1. Make a Live key in Firm › Developers. Every live account gets ₹250 of free calls each calendar month, with no card.
  2. Swap the key in AOS_KEY. The code does not change.
  3. Call a real CNR. A live CNR with a test key is refused with test_mode_live_cnr, so you cannot do this by accident.

#Where next

PreviousDeveloper platformNext Authentication