API reference
Searches
Submit, read, list, cancel and download. For the concepts behind these calls, read Search lifecycle.
Submit searches
| Body field | Type | Required | Description |
|---|---|---|---|
state | string | Yes | State key, for example telangana. |
search_type | string | Yes | Search key, for example ec. See the States pages. |
params | object | Yes | The search parameters. Each search page lists them. |
label | string | No | Your own reference. Returned on every read. |
callback_url | string | No | HTTPS URL to receive the result. See Webhooks. |
searches | array | Batch | Up to 25 items of the same shape, instead of the single fields above. callback_url may sit at the top. |
| Header | Description |
|---|---|
Idempotency-Key | Optional. 1 to 255 printable ASCII characters, no spaces. A retry within 24 hours is free and returns the original. |
Returns 202 with data.searches[] and data.rejected[]. It returns 200 when every item was an idempotent replay and 400 when nothing was accepted. Response headers include X-RateLimit-Limit and X-RateLimit-Remaining.
Get a search
id is the public id, for example SRCH-2026-A1B2C3D4. Returns the search object with its current status, and its records and documents once it has finished.
{
"data": {
"id": "SRCH-2026-A1B2C3D4",
"state": "andhra",
"search_type": "rera",
"label": "Case 8841",
"status": "succeeded",
"progress": 100,
"note": null,
"found": true,
"records": [ { "...": "shape varies by search" } ],
"record_count": 1,
"documents": [ { "filename": "result.pdf", "content_type": "application/pdf", "bytes": 184233, "withheld": false } ],
"error": null,
"refunded": false,
"replayed": false,
"batch_id": null,
"recovery_of": null,
"source": "api",
"created_at": "2026-10-05T10:00:00Z",
"completed_at": "2026-10-05T10:03:12Z",
"portal_read_at": "2026-10-05T10:03:12Z"
}
}portal_read_at is when the government portal was read for this result, or null when it was not recorded. When it is earlier than created_at, the result is a public record that LegiScore read from the portal a short time before, delivered to this search with its own id and its own copies of the documents. It is charged as a normal search, and every document shows the record as of that time. Encumbrance certificates and searches by a person's name or mobile number are never delivered this way.
List searches
| Query | Description |
|---|---|
limit | Default 50, at most 200. |
offset | Rows to skip. |
status | Filter by status. |
batch_id | Only searches from one batch. |
Cancel a search
Cancels a search that has not finished and refunds it when the service confirms. A finished search returns 409 already_finished.
Download a document
Returns 302 to a signed URL valid for one hour. Use filename from documents[]. A file that failed its integrity check returns 410 withheld.
Provide an OTP
{ "otp": "123456" }Only for a search in awaiting_otp that needs a code sent to your own registered mobile. Most searches never need this. Wrong state returns 409 not_waiting, a bad code 400 invalid_otp.
AI Recovery
Charged per use. On an incomplete result, tries related identifiers and returns a new search that points back with recovery_of. Refunded if there is nothing defensible to try. Searches that send an OTP are refused with recovery_unavailable. Optional body: { "callback_url": "https://..." }.
AI Assist
Charged per use. Multipart form with state and either file (PDF or image, up to 20 MB) or text. We read it and propose search parameters. Nothing is submitted until you submit it yourself. Charged only when something was extracted.