Reports API

A report searches the public court records for a person or a company and gathers what it finds into one document. Reports run in the background: you order one, and read it when it is ready. All calls need the scope reports:write. Prices are in credits (1 credit is ₹1 before GST); see pricing.

A report is public court records only. It is not a police verification, and it does not say a person is or is not honest. A name match is a lead, not proof.

You are charged when the report completes. A report that finishes and finds no case is still charged, because the search was done. A report that fails is free. In test mode a report runs on sandbox parties only and costs nothing.

#Order a report

POST /reports · litigation check ₹79, then ₹59 from 1,000 a month, ₹45 from 10,000 a month · due diligence ₹299, then ₹249 from 500 a month

Field	Meaning
type	litigation_check or due_diligence. Required.
subject.kind	person or company. Required.
subject.name	The person's or company's name, at least 3 letters. Required.
subject.father_name	A person's father's name. Strongly narrows matches; send it when you have it.
subject.cin	A company's 21-character Corporate Identity Number. A CIN found in a record confirms the match.
subject.state, subject.district	Where to look first. A record that names them scores higher.
subject.entities	due_diligence only, at most 25. Group entities, promoters and directors, each checked like the subject. See due diligence.

The call answers 202 at once with status: queued. A live report on a real person needs a paid account, because a name search does; see errors. Every name searched is logged, and cases in protected categories are masked. An account may have 100 reports queued or running at a time; more gives 429 too_many_reports.

curl -X POST https://adv.heliosynctech.com/api/v1/reports \
  -H "Authorization: Bearer $AOS_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: c4a8e6d2-1b3f-4d5a-9e7c-0a2b4d6f8e66" \
  -d '{
    "type": "litigation_check",
    "subject": { "kind": "company", "name": "Sandbox Lender Finance Ltd", "state": "Delhi" }
  }'

{
  "object": "report",
  "id": "rpt_3cJ8vNd5Qw2TzXa7Uf4LbYh9",
  "type": "litigation_check",
  "status": "queued",
  "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": null,
  "pdf_url": null,
  "verify_url": null,
  "note": null,
  "error": null
}

Always send an Idempotency-Key; see idempotency.

#Read a report

GET /reports/{id} · free

status goes queued, running, then completed or failed. The report.completed and report.failed events reach your webhook endpoints as soon as it ends, so you do not need to poll. A report is private to the account and mode that ordered it: another firm's report, or a test report read with a live key, is 404 report_not_found.

curl https://adv.heliosynctech.com/api/v1/reports/rpt_3cJ8vNd5Qw2TzXa7Uf4LbYh9 -H "Authorization: Bearer $AOS_KEY"

{
  "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_risk": { "protected": 0, "ibc": 0, "sarfaesi": 0, "drt": 0, "cheque_bounce": 0, "criminal": 0, "consumer": 0, "recovery": 5, "other": 0 },
    "by_confidence": { "high": 5, "medium": 0, "low": 0 },
    "forums_checked": ["sandbox_high_court"],
    "truncated": false,
    "checked_at": "2026-12-01T10:20:03+05:30"
  },
  "hits": [
    {
      "forum": "sandbox_high_court",
      "court": "Sandbox High Court, North Bench",
      "case_number": "CS(COMM) 5131/2026",
      "cnr": "SBXX010001012026",
      "case_type": "Commercial Suit",
      "parties": { "petitioner": "Sandbox Lender Finance Ltd", "respondent": "Neha Saxena" },
      "role": "petitioner",
      "status": "pending",
      "next_date": "2026-12-18",
      "decision_date": null,
      "last_listed": null,
      "risk": "recovery",
      "flags": ["recovery"],
      "protected": false,
      "source": "sandbox",
      "source_id": null,
      "match": { "confidence": "high", "score": 95, "reasons": ["exact name"], "corroborated": false },
      "entity": { "name": "Sandbox Lender Finance Ltd", "relation": "subject" }
    }
  ]
}

(The links are absolute, on the host you called. hits is shortened here: that report has five.)

#The summary

Field	Meaning
cases_found	Hits in all. A report with 0 here is a finished check that found nothing, and is charged.
possible_matches	How many hits are low confidence.
by_risk	Cases counted under the most serious flag each carries. Keys, most serious first: protected, ibc, sarfaesi, drt, cheque_bounce, criminal, consumer, recovery, other. The counts add up to cases_found.
by_confidence	Hits by match confidence: high, medium, low.
forums_checked	Where we looked: district_court, high_court, supreme_court, tribunal, cause_list; sandbox_high_court for a test key.
truncated	True when a very common name matched more records than we read. Add a father's name, CIN, state or district and order again.
checked_at	When the search ran.

#A hit

Each hit is one case that could be the subject's.

Field	Meaning
forum, court, case_number, cnr, case_type	Where it is and what it is. cnr and case_number can be null.
parties	petitioner and respondent. Shown as [name withheld: protected category] for a protected case.
role	The side the subject matched: petitioner or respondent.
status	pending, disposed, listed, decided or order.
next_date, decision_date, last_listed	yyyy-MM-dd or null.
risk, flags	The most serious class, and every class that applies.
protected	True for POCSO, sexual-offence, matrimonial and juvenile cases. Details are withheld.
source, source_id	Where the record came from: court_cases, cause_list, judgment, tribunal_order or sandbox.
match	How sure we are the name is the subject. See below.
entity	Which name this hit is for: the subject, or an entity of a due-diligence report.

#How sure a match is

match.score is 50 to 100. A name that scores under 50 is not a hit at all. The score sets match.confidence:

Confidence	Score	Read it as
high	90 and above	The name matches closely, such as an exact name.
medium	70 to 89	A likely match, for example initials expanded. Check it.
low	50 to 69	A lead only. Confirm it before you act.

match.reasons says why in plain words. match.corroborated is true when the father's name, the CIN, the state or the district also agrees. A father's name that differs rules a record out.

#Due diligence

A due_diligence report is run on a company, and also checks its group entities, promoters and directors. Send subject.kind: company (a person gets 400 due_diligence_needs_company) and list the others in subject.entities, up to 25:

curl -X POST https://adv.heliosynctech.com/api/v1/reports \
  -H "Authorization: Bearer $AOS_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7e1d3b5f-9a2c-4e6d-8b0f-1c3e5a7d9f12" \
  -d '{
    "type": "due_diligence",
    "subject": {
      "kind": "company", "name": "Sandbox Lender Finance Ltd", "state": "Delhi",
      "entities": [
        { "name": "Sandbox Holdings Pvt Ltd", "kind": "company", "relation": "group_entity" },
        { "name": "Aarav Sharma", "kind": "person", "relation": "director", "father_name": "Rajesh Sharma" }
      ]
    }
  }'

relation is group_entity, promoter or director. The result has the same summary and hits, each hit tagged with its entity, plus entities: the counts for each name checked, as { name, relation, kind, cases_found, possible_matches, by_risk, by_confidence }. Sending entities with a litigation check is refused.

#List reports

GET /reports · free

Your reports, newest first, with the summary but not the hits. Filter with status (queued, running, completed, failed) and type. See pagination.

#Download the PDF

GET /reports/{id}/pdf · free

The report as a PDF, with a QR code anyone can scan to confirm it is genuine and unchanged. The pdf_url of a completed report points here; fetch it with your key. Ask only after completed: before then you get 409 report_not_ready. If the PDF could not be laid out, the report still completes and is charged (the search is the product), pdf_url is null, note says so, and this call answers 404 pdf_unavailable; order the report again for a PDF.

curl https://adv.heliosynctech.com/api/v1/reports/rpt_3cJ8vNd5Qw2TzXa7Uf4LbYh9/pdf -H "Authorization: Bearer $AOS_KEY" -o report.pdf

#When a report fails

status is failed, error.message says why, nothing is charged, and a report.failed event is sent. Order it again.

#Report types

Type	What it covers	Price
litigation_check	Cases in which the subject is a party, across the courts we read, with status and next date.	₹79, then ₹59 from 1,000 a month, ₹45 from 10,000 a month
due_diligence	A litigation check on a company and up to 25 group entities, promoters and directors, with the counts for each.	₹299, then ₹249 from 500 a month

The price falls as you order more in the month; see pricing. For a worked example, see litigation check for lenders.