# Historical Cases Search API

Source: https://caseprimus.ai/docs/historical-cases-search-api

## API To Search A Company's Historical Court Cases Across Indian Courts

The **Historical Cases Search API** returns the court cases a company has been named in, past and present, without putting it under monitoring. Send a company name, with an optional registration number and address to sharpen matching, and get the first page of 100 cases in the same call.

Built for due diligence, onboarding, credit decisions and vendor screening, it can look for the company as petitioner, respondent or both, can be filtered by year and case status, and pages through large histories with a token. Results are kept for 7 days.

> **Built on certified infrastructure.** CasePrimus.ai is operated by Pegadroid IQ Solutions Private Limited, the legal entity behind Attestr's products, which holds ISO/IEC 27001:2022 certification. Data is hosted in India (AWS Mumbai, ap-south-1) and every connection is encrypted in transit.

## Key capabilities

- **The first page in one call.** The start call returns up to 100 cases straight away, with a `searchId` and a `nextPageToken`.
- **Page through the full history.** Pass the `nextPageToken` to read the next 100. A case is never returned twice.
- **Petitioner, respondent or both.** Use `partyType` to choose which side the company must be on. The default is both.
- **Filter by year and status.** Limit the search to cases filed between two years, and to pending or disposed cases.
- **Name variations.** AI generates further spellings of the company name, and you can add up to 25 of your own.
- **Sharper matching.** Add a registration number, such as a CIN, and an address to reduce false matches.
- **Safe to retry.** Repeating a page request with the same token returns the same page, and a `clientReference` makes a repeated start call safe.

## How it works

1. **Start a search.** Post the company's name, with any filters, to `POST /historical-search`. You get the first 100 cases, a `searchId` and a `nextPageToken`.
2. **Page through the rest.** Send the `nextPageToken` as `pageToken` to `GET /historical-search/{searchId}/results` for the next 100.
3. **Stop at the end.** The history is complete when `nextPageToken` is `null` and the status is `COMPLETE`.

## API definition

### Start a historical search

Searches a company's court-case history without adding it to a watchlist, and returns the first page in the same call: 100 cases (fewer only when that is all there is), a searchId and a nextPageToken (null when there is nothing more). Cases come newest filing date first unless filters.sortBy says otherwise, and a case is never returned twice. filters.courtTypes restricts the search to the courts given - SC, HC, DC, or OTHER for the tribunals and everything else; omit it to search every court. If the page cannot be assembled within 60 seconds the call returns 503 with Retry-After and nothing is delivered. Send the same clientReference with the same request within 24 hours to get the same search and first page again. Asynchronous mode: send "mode": "ASYNC" to have the whole result set collected in the background. The call returns 202 with status RUNNING, and the status becomes COMPLETE or FAILED when it finishes; subscribe a webhook to historical_search.finished to be told, then read the results page by page. Asynchronous mode is available on some plans. Results are kept for 7 days. fromYear and toYear cannot be later than the current year, and fromYear cannot be later than toYear. Only companies can be searched; a person is refused. Requires historicalSearch.write.

**Request URL**

`POST https://api.caseprimus.ai/api/caseprimus/v1/historical-search`

**Request headers**

| Type | Name | Value | Optional |
| --- | --- | --- | --- |
| String | `Content-Type` | `application/json` | Required |
| String | `X-CasePrimus-Api-Key` | Your API key | Required |

**Input parameters**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Required | The company's name. 2 to 255 characters |
| `entityType` | enum | Optional | BUSINESS only (the default). PERSON is accepted by the format check but refused with 400 PERSON_SEARCH_NOT_SUPPORTED (60405). One of: BUSINESS, PERSON |
| `registrationNumber` | string or null | Optional | Optional, e.g. CIN. Sharpens matching. More than one identifier fits. up to 100 characters |
| `location` | string or null | Optional | Optional address. Sharpens matching. up to 4192 characters |
| `nameVariations` | array of string | Optional | Other spellings of the name. Added to any generated ones (at most 25 variations are used in all). |
| `autoNameVariations` | boolean | Optional | Generate further spellings of the name (adds a few seconds to the first call). |
| `partyType` | enum | Optional | The side the company must be on. One of: PETITIONER, RESPONDENT, BOTH |
| `filters` | object | Optional | Fixed for the life of the search. Applied by the data sources, so a narrower search costs less. |
| `filters.fromYear` | integer or null | Optional | Cases filed in this year or later. Not later than the current year, and not later than toYear. minimum 1950 |
| `filters.toYear` | integer or null | Optional | Cases filed in this year or earlier. Not later than the current year. minimum 1950 |
| `filters.caseStatus` | enum | Optional | Filter on whether the case is pending or disposed. These are the filter values; the results' own caseStatus is written as the data source writes it (for example Pending). One of: ALL, PENDING, DISPOSED |
| `filters.courtTypes` | array of enum | Optional | Search only these courts. SC the Supreme Court, HC the High Courts, DC the District Courts, and OTHER everything else - the consumer commissions, NCLT, NCLAT, CESTAT, ITAT, DRT, DRAT, GSTAT, NGT, SAT, APTEL and any court that cannot be placed. Omit it to search every court. The four are exactly the groups the sources can tell apart, so narrowing reads fewer pages rather than discarding them; a page still costs the same. One of: SC, HC, DC, OTHER |
| `filters.sortBy` | enum | Optional | Order by filing date: filing_desc is newest first (the default), filing_asc oldest first. Applied by the data source, so it orders the whole result set and not just the page you are looking at. One of: filing_desc, filing_asc |
| `clientReference` | string | Optional | Your own reference. Also makes a repeated start call safe to retry: the same reference with the same request within 24 hours returns the same search and first page. 1 to 50 characters |
| `mode` | enum | Optional | SYNC (default) returns the first page now and you page through the rest. ASYNC collects every result in the background: the call returns 202 with the searchId and you are told when it is COMPLETE (see the endpoint description). ASYNC needs a plan that has it (per-search plans do); otherwise 403. One of: SYNC, ASYNC |

**Sample request**

```bash
BASE="https://api.caseprimus.ai/api/caseprimus/v1"

curl -X POST "$BASE/historical-search" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Logistics Private Limited",
    "entityType": "BUSINESS",
    "registrationNumber": "U63090MH2012PTC123456",
    "partyType": "BOTH",
    "filters": {
      "caseStatus": "ALL"
    },
    "clientReference": "vendor-onboarding-4821"
  }'
```

**Responses**

- `200`: The first page (mode SYNC).
- `202`: Accepted (mode ASYNC). The search is RUNNING; there are no results yet.
- `400`: Invalid input (60001), invalid filters or party type (`HISTORICAL_SEARCH_INVALID_FILTER`, 61454), or a person search (`PERSON_SEARCH_NOT_SUPPORTED`, 60405).
- `402`: The plan's search allowance is used up (`HISTORICAL_SEARCH_QUOTA_EXCEEDED`, 61455).
- `403`: Caller lacks historicalSearch.write; no data source is enabled for the account (`HISTORICAL_SEARCH_NO_PROVIDER`, 61456); or (mode ASYNC) asynchronous collection is not available on the plan (`HISTORICAL_SEARCH_ASYNC_NOT_AVAILABLE`, 61465).
- `429`: Too many requests for this account (`SEARCH_RATE_LIMIT_EXCEEDED`, 61457; `details.retryAfterSeconds` and `details.window`), or (mode ASYNC) too many asynchronous searches still collecting (`HISTORICAL_SEARCH_TOO_MANY_RUNNING`, 61466). See `Retry-After`; the first also carries `X-RateLimit-*`.
- `503`: The first page could not be assembled in time (`HISTORICAL_SEARCH_PAGE_NOT_READY`, 61452; `details` carry `searchId`, `nextPageToken`, `retryAfterSeconds`, `heldForNextPage`; `Retry-After` header). Retry; nothing was delivered or charged. In mode ASYNC, also returned when background collection cannot be queued (`HISTORICAL_SEARCH_ASYNC_NOT_AVAILABLE`, 61465) - nothing is stored.

**Response fields (HTTP 200)**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `searchId` | string |  | The id of this search. Use it to read further pages. |
| `mode` | enum |  | ASYNC: collected in the background (see POST /historical-search). One of: SYNC, ASYNC |
| `status` | enum |  | SYNC searches are ACTIVE, COMPLETE or EXPIRED. ASYNC searches are RUNNING, COMPLETE, FAILED or EXPIRED. One of: ACTIVE, COMPLETE, EXPIRED, RUNNING, FAILED |
| `name` | string |  | The company name that was searched for. |
| `partyType` | enum |  | One of: PETITIONER, RESPONDENT, BOTH |
| `filters` | object |  | The filters the search was started with. Always these three keys; fromYear and toYear are null when not given, caseStatus is ALL when not given. Fixed for the life of the search. |
| `filters.fromYear` | integer or null |  |  |
| `filters.toYear` | integer or null |  |  |
| `filters.caseStatus` | enum |  | One of: ALL, PENDING, DISPOSED |
| `clientReference` | string or null |  | Your own reference, if you sent one. |
| `delivered` | integer |  | Results delivered so far. For a COMPLETE asynchronous search: all of them (reading its pages is free and repeatable). |
| `collected` | integer |  | ASYNC only. Results stored so far; final once COMPLETE. |
| `completedAt` | integer or null |  | ASYNC only. Epoch ms the search finished (COMPLETE or FAILED); null while RUNNING. |
| `failureReason` | string |  | ASYNC only, present when FAILED: why, in words for a person. Nothing was charged. |
| `warnings` | array of object |  | Empty when there is nothing to report (and always empty once EXPIRED). |
| `warnings[].code` | enum |  | RESULT_CAP_REACHED: the search stopped at the results-per-search limit of the plan and more existed - narrow the filters. SOURCE_UNAVAILABLE: a data source kept failing, so the search finished without it; the results delivered are valid. One of: RESULT_CAP_REACHED, SOURCE_UNAVAILABLE |
| `warnings[].message` | string |  |  |
| `createdAt` | integer |  | Epoch ms. |
| `expiresAt` | integer |  | Epoch ms. Results are deleted at this time. |
| `pageSize` | integer |  | The number of cases on a full page: 100. |
| `results` | array of object |  | The cases on this page. |
| `results[].caseRef` | string |  | Stable id of the case: the same case has the same caseRef in every search. Always `cr_` followed by 16 hexadecimal characters. |
| `results[].caseIdentifier` | object or null |  | What identifies the case for a live lookup (see CaseIdentifier for the fields). A case identified by its CNR carries `courtType` (SC, HC or DC) and `cnr`, so it can be passed as it is to POST /case-lookup; where the court type is not known it carries just `cnr`. A tribunal or consumer case carries its full identifier, courtType included. Null when it cannot be established without a live check (identifierStatus is then NEEDS_CONFIRMATION). |
| `results[].identifierStatus` | enum |  | CONFIRMED when caseIdentifier is set; NEEDS_CONFIRMATION when it is null. One of: CONFIRMED, NEEDS_CONFIRMATION |
| `results[].courtType` | enum |  | The kind of court. OTHER when the court could not be classified. One of: DC, HC, SC, CC, NCLT, NCLAT, CESTAT, DRT, DRAT, GSTAT, ITAT, APTEL, NGT, SAT, OTHER |
| `results[].court` | string or null |  | The court the case is in. |
| `results[].state` | string or null |  | The state the court is in. |
| `results[].district` | string or null |  | The district, for courts that have one. |
| `results[].bench` | string or null |  | The bench, for courts that have benches. |
| `results[].caseType` | string or null |  | The court's short code for the type of case, for example WP. |
| `results[].caseTypeName` | string or null |  | The full name of the case type, for example Writ Petition. |
| `results[].caseNature` | string or null |  | The nature of the case, for example Civil. |
| `results[].caseNumber` | string or null |  | The case number as the court writes it. |
| `results[].cnrNumber` | string or null |  | Null when the case has no customer-visible CNR. |
| `results[].filingNumber` | string or null |  | The number the case was filed under. |
| `results[].registrationNumber` | string or null |  | The number the case was registered under. |
| `results[].filingDate` | string or null |  | YYYY-MM-DD. |
| `results[].filingYear` | integer or null |  | The year the case was filed. |
| `results[].registrationDate` | string or null |  | YYYY-MM-DD (as the court wrote it if it could not be read as a date). |
| `results[].caseStatus` | string or null |  | The status exactly as the data source writes it, so the casing varies (for example Pending, Disposed or PENDING). Do not compare it with the PENDING / DISPOSED / ALL values of the search's caseStatus filter without ignoring case. |
| `results[].nextHearingDate` | string or null |  | YYYY-MM-DD (as the court wrote it if it could not be read as a date). |
| `results[].decisionDate` | string or null |  | YYYY-MM-DD (as the court wrote it if it could not be read as a date). |
| `results[].natureOfDisposal` | string or null |  | How the case was disposed of, for a decided case. |
| `results[].petitioner` | string or null |  | The petitioner named for the case. |
| `results[].respondent` | string or null |  | The respondent named for the case. |
| `results[].partyRole` | enum or null |  | The side the searched company is on. One of: PETITIONER, RESPONDENT, BOTH |
| `results[].matchedParty` | string or null |  | The party that made this case match: the first party, on the side(s) searched, that carries the company's name or one of its variations, as the court wrote it (for example 'Acme Logistics Pvt. Ltd' when it is respondent 6 of 8). `petitioner` and `respondent` above are only the parties on the case's title line, so they may not include it. |
| `results[].petitioners` | array of string |  | Every petitioner, each once, in the court's order (placeholder entries such as 'Respondent' are left out). At most 25 - see `partyCountTruncated`. |
| `results[].respondents` | array of string |  | Every respondent, each once, in the court's order. At most 25 - see `partyCountTruncated`. |
| `results[].partyCountTruncated` | boolean |  | True when either list was cut at 25. `matchedParty` is still named. |
| `nextPageToken` | string or null |  | Pass it as pageToken to get the next page. A signed, opaque string tied to this search: do not build or alter it (a wrong one is refused with 400). Null when there is nothing more. |

**Example response (200)**

```json
{
  "searchId": "CPHS0exampledemo0001",
  "mode": "SYNC",
  "status": "ACTIVE",
  "name": "Acme Logistics Private Limited",
  "partyType": "BOTH",
  "filters": {
    "fromYear": null,
    "toYear": null,
    "caseStatus": "ALL"
  },
  "clientReference": "vendor-onboarding-4821",
  "delivered": 100,
  "warnings": [],
  "createdAt": 1791600000000,
  "expiresAt": 1792204800000,
  "pageSize": 100,
  "results": [
    {
      "caseRef": "cr_51ff1354f54a87d5",
      "caseIdentifier": {
        "courtType": "HC",
        "cnr": "KAHC010123452024"
      },
      "identifierStatus": "CONFIRMED",
      "courtType": "HC",
      "court": "High Court of Karnataka",
      "state": "Karnataka",
      "district": null,
      "bench": null,
      "caseType": "WP",
      "caseTypeName": "Writ Petition",
      "caseNature": null,
      "caseNumber": "WP/12345/2024",
      "cnrNumber": "KAHC010123452024",
      "filingNumber": "WP/45120/2024",
      "registrationNumber": "WP/12345/2024",
      "filingDate": "2024-03-18",
      "filingYear": 2024,
      "registrationDate": "2024-03-21",
      "caseStatus": "Pending",
      "nextHearingDate": "2026-11-04",
      "decisionDate": null,
      "natureOfDisposal": null,
      "petitioner": "K. Ramesh Babu",
      "respondent": "The State of Karnataka, The Principal Secretary, Revenue Department, The Deputy Commissioner, Acme Logistics Pvt. Ltd, Indian Oil Corporation Ltd",
      "partyRole": "RESPONDENT",
      "matchedParty": "Acme Logistics Pvt. Ltd",
      "petitioners": [
        "K. Ramesh Babu"
      ],
      "respondents": [
        "The State of Karnataka",
        "The Principal Secretary, Revenue Department",
        "The Deputy Commissioner",
        "Acme Logistics Pvt. Ltd",
        "Indian Oil Corporation Ltd"
      ],
      "partyCountTruncated": false
    },
    {
      "caseRef": "cr_123e0077c97f23bc",
      "caseIdentifier": {
        "courtType": "DC",
        "cnr": "DLST010012342023"
      },
      "identifierStatus": "CONFIRMED",
      "courtType": "DC",
      "court": "Saket District Court, Delhi",
      "state": "Delhi",
      "district": "South Delhi",
      "bench": null,
      "caseType": "CS",
      "caseTypeName": "Civil Suit",
      "caseNature": null,
      "caseNumber": "1234/2023",
      "cnrNumber": "DLST010012342023",
      "filingNumber": "1234/2023",
      "registrationNumber": "1234/2023",
      "filingDate": "2023-06-02",
      "filingYear": 2023,
      "registrationDate": "2023-06-05",
      "caseStatus": "Disposed",
      "nextHearingDate": null,
      "decisionDate": "2025-01-29",
      "natureOfDisposal": "Decreed",
      "petitioner": "BLUELINE FREIGHT SERVICES",
      "respondent": "ACME LOGISTICS PRIVATE LIMITED",
      "partyRole": "RESPONDENT",
      "matchedParty": "ACME LOGISTICS PRIVATE LIMITED",
      "petitioners": [
        "BLUELINE FREIGHT SERVICES"
      ],
      "respondents": [
        "ACME LOGISTICS PRIVATE LIMITED"
      ],
      "partyCountTruncated": false
    },
    {
      "caseRef": "cr_42ec81178b2c1da7",
      "caseIdentifier": {
        "courtType": "ITAT",
        "establishmentCode": "MUMBAI",
        "caseType": "ITA",
        "registrationNumber": "2210/2022"
      },
      "identifierStatus": "CONFIRMED",
      "courtType": "ITAT",
      "court": "Income Tax Appellate Tribunal",
      "state": "Maharashtra",
      "district": null,
      "bench": "Mumbai",
      "caseType": "ITA",
      "caseTypeName": "Income Tax Appeal",
      "caseNature": "Civil",
      "caseNumber": "ITA 2210/MUM/2022",
      "cnrNumber": null,
      "filingNumber": null,
      "registrationNumber": "2210/2022",
      "filingDate": "2022-09-14",
      "filingYear": 2022,
      "registrationDate": null,
      "caseStatus": "Pending",
      "nextHearingDate": null,
      "decisionDate": null,
      "natureOfDisposal": null,
      "petitioner": "ACME LOGISTICS PRIVATE LIMITED",
      "respondent": "DCIT CIRCLE 4(1)",
      "partyRole": "PETITIONER",
      "matchedParty": "ACME LOGISTICS PRIVATE LIMITED",
      "petitioners": [
        "ACME LOGISTICS PRIVATE LIMITED"
      ],
      "respondents": [
        "DCIT CIRCLE 4(1)"
      ],
      "partyCountTruncated": false
    }
  ],
  "nextPageToken": "eyJzIjoiQ1BIUzBleGFtcGxlZGVtbzAwMDEiLCJwIjoxMDB9.0kQjJtYRBsIazMj45LlfiSe7R-ZlsjATarNBpOcql-w"
}
```

### Get the next page of a search

Returns the next 100 cases after pageToken. Without a pageToken it returns the first page again. Every page has exactly 100 cases except the last, and a case is never returned twice. Repeating a call with the same token returns the same page, so it is safe to retry. The end is nextPageToken null with status COMPLETE. If the page cannot be assembled within 60 seconds the call returns 503 with Retry-After; retry with the same token. Another request already running on the same search returns 409. An asynchronous search can be read once it is COMPLETE. Searches older than 7 days return 410. The pageToken is an opaque, signed string: use only the nextPageToken the API gave you, for this search; any other value is refused with 400. Requires historicalSearch.read.

**Request URL**

`GET https://api.caseprimus.ai/api/caseprimus/v1/historical-search/{searchId}/results`

**Request headers**

| Type | Name | Value | Optional |
| --- | --- | --- | --- |
| String | `X-CasePrimus-Api-Key` | Your API key | Required |

**Parameters**

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `searchId` | path | Required | The searchId returned when the search was started. |
| `pageToken` | query | Optional | The `nextPageToken` of the previous page. Leave it out to get the FIRST page again (the page the start call returned has no token of its own). |

**Sample request**

```bash
BASE="https://api.caseprimus.ai/api/caseprimus/v1"

curl "$BASE/historical-search/SEARCH_ID/results" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"
```

**Responses**

- `200`: The page.
- `400`: Invalid page token (`HISTORICAL_SEARCH_INVALID_TOKEN`, 61453; a token from another search, altered, or beyond what has been delivered), or a malformed searchId (60001).
- `402`: The plan's search allowance is used up (`HISTORICAL_SEARCH_QUOTA_EXCEEDED`, 61455).
- `403`: Caller lacks historicalSearch.read.
- `404`: Unknown or deleted search (`HISTORICAL_SEARCH_NOT_FOUND`, 61449).
- `409`: Another request on this search is still running (`HISTORICAL_SEARCH_BUSY`, 61451; no `details`, `Retry-After` header), or an asynchronous search is not COMPLETE yet (`HISTORICAL_SEARCH_NOT_COMPLETE`, 61467; `details.status` is RUNNING or FAILED).
- `410`: The search has expired and its results were deleted (`HISTORICAL_SEARCH_EXPIRED`, 61450).
- `429`: Too many requests for this account (`SEARCH_RATE_LIMIT_EXCEEDED`, 61457). See `Retry-After` and `X-RateLimit-*`.
- `503`: The page could not be assembled in time (`HISTORICAL_SEARCH_PAGE_NOT_READY`, 61452; `Retry-After` header and `details.retryAfterSeconds`). Retry with the same token; nothing was delivered or charged.

**Response fields (HTTP 200)**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `searchId` | string |  | The id of this search. Use it to read further pages. |
| `mode` | enum |  | ASYNC: collected in the background (see POST /historical-search). One of: SYNC, ASYNC |
| `status` | enum |  | SYNC searches are ACTIVE, COMPLETE or EXPIRED. ASYNC searches are RUNNING, COMPLETE, FAILED or EXPIRED. One of: ACTIVE, COMPLETE, EXPIRED, RUNNING, FAILED |
| `name` | string |  | The company name that was searched for. |
| `partyType` | enum |  | One of: PETITIONER, RESPONDENT, BOTH |
| `filters` | object |  | The filters the search was started with. Always these three keys; fromYear and toYear are null when not given, caseStatus is ALL when not given. Fixed for the life of the search. |
| `filters.fromYear` | integer or null |  |  |
| `filters.toYear` | integer or null |  |  |
| `filters.caseStatus` | enum |  | One of: ALL, PENDING, DISPOSED |
| `clientReference` | string or null |  | Your own reference, if you sent one. |
| `delivered` | integer |  | Results delivered so far. For a COMPLETE asynchronous search: all of them (reading its pages is free and repeatable). |
| `collected` | integer |  | ASYNC only. Results stored so far; final once COMPLETE. |
| `completedAt` | integer or null |  | ASYNC only. Epoch ms the search finished (COMPLETE or FAILED); null while RUNNING. |
| `failureReason` | string |  | ASYNC only, present when FAILED: why, in words for a person. Nothing was charged. |
| `warnings` | array of object |  | Empty when there is nothing to report (and always empty once EXPIRED). |
| `warnings[].code` | enum |  | RESULT_CAP_REACHED: the search stopped at the results-per-search limit of the plan and more existed - narrow the filters. SOURCE_UNAVAILABLE: a data source kept failing, so the search finished without it; the results delivered are valid. One of: RESULT_CAP_REACHED, SOURCE_UNAVAILABLE |
| `warnings[].message` | string |  |  |
| `createdAt` | integer |  | Epoch ms. |
| `expiresAt` | integer |  | Epoch ms. Results are deleted at this time. |
| `pageSize` | integer |  | The number of cases on a full page: 100. |
| `results` | array of object |  | The cases on this page. |
| `results[].caseRef` | string |  | Stable id of the case: the same case has the same caseRef in every search. Always `cr_` followed by 16 hexadecimal characters. |
| `results[].caseIdentifier` | object or null |  | What identifies the case for a live lookup (see CaseIdentifier for the fields). A case identified by its CNR carries `courtType` (SC, HC or DC) and `cnr`, so it can be passed as it is to POST /case-lookup; where the court type is not known it carries just `cnr`. A tribunal or consumer case carries its full identifier, courtType included. Null when it cannot be established without a live check (identifierStatus is then NEEDS_CONFIRMATION). |
| `results[].identifierStatus` | enum |  | CONFIRMED when caseIdentifier is set; NEEDS_CONFIRMATION when it is null. One of: CONFIRMED, NEEDS_CONFIRMATION |
| `results[].courtType` | enum |  | The kind of court. OTHER when the court could not be classified. One of: DC, HC, SC, CC, NCLT, NCLAT, CESTAT, DRT, DRAT, GSTAT, ITAT, APTEL, NGT, SAT, OTHER |
| `results[].court` | string or null |  | The court the case is in. |
| `results[].state` | string or null |  | The state the court is in. |
| `results[].district` | string or null |  | The district, for courts that have one. |
| `results[].bench` | string or null |  | The bench, for courts that have benches. |
| `results[].caseType` | string or null |  | The court's short code for the type of case, for example WP. |
| `results[].caseTypeName` | string or null |  | The full name of the case type, for example Writ Petition. |
| `results[].caseNature` | string or null |  | The nature of the case, for example Civil. |
| `results[].caseNumber` | string or null |  | The case number as the court writes it. |
| `results[].cnrNumber` | string or null |  | Null when the case has no customer-visible CNR. |
| `results[].filingNumber` | string or null |  | The number the case was filed under. |
| `results[].registrationNumber` | string or null |  | The number the case was registered under. |
| `results[].filingDate` | string or null |  | YYYY-MM-DD. |
| `results[].filingYear` | integer or null |  | The year the case was filed. |
| `results[].registrationDate` | string or null |  | YYYY-MM-DD (as the court wrote it if it could not be read as a date). |
| `results[].caseStatus` | string or null |  | The status exactly as the data source writes it, so the casing varies (for example Pending, Disposed or PENDING). Do not compare it with the PENDING / DISPOSED / ALL values of the search's caseStatus filter without ignoring case. |
| `results[].nextHearingDate` | string or null |  | YYYY-MM-DD (as the court wrote it if it could not be read as a date). |
| `results[].decisionDate` | string or null |  | YYYY-MM-DD (as the court wrote it if it could not be read as a date). |
| `results[].natureOfDisposal` | string or null |  | How the case was disposed of, for a decided case. |
| `results[].petitioner` | string or null |  | The petitioner named for the case. |
| `results[].respondent` | string or null |  | The respondent named for the case. |
| `results[].partyRole` | enum or null |  | The side the searched company is on. One of: PETITIONER, RESPONDENT, BOTH |
| `results[].matchedParty` | string or null |  | The party that made this case match: the first party, on the side(s) searched, that carries the company's name or one of its variations, as the court wrote it (for example 'Acme Logistics Pvt. Ltd' when it is respondent 6 of 8). `petitioner` and `respondent` above are only the parties on the case's title line, so they may not include it. |
| `results[].petitioners` | array of string |  | Every petitioner, each once, in the court's order (placeholder entries such as 'Respondent' are left out). At most 25 - see `partyCountTruncated`. |
| `results[].respondents` | array of string |  | Every respondent, each once, in the court's order. At most 25 - see `partyCountTruncated`. |
| `results[].partyCountTruncated` | boolean |  | True when either list was cut at 25. `matchedParty` is still named. |
| `nextPageToken` | string or null |  | Pass it as pageToken to get the next page. A signed, opaque string tied to this search: do not build or alter it (a wrong one is refused with 400). Null when there is nothing more. |

**Example response (200)**

```json
{
  "searchId": "CPHS0exampledemo0001",
  "mode": "SYNC",
  "status": "ACTIVE",
  "name": "Acme Logistics Private Limited",
  "partyType": "BOTH",
  "filters": {
    "fromYear": null,
    "toYear": null,
    "caseStatus": "ALL"
  },
  "clientReference": "vendor-onboarding-4821",
  "delivered": 100,
  "warnings": [],
  "createdAt": 1791600000000,
  "expiresAt": 1792204800000,
  "pageSize": 100,
  "results": [
    {
      "caseRef": "cr_51ff1354f54a87d5",
      "caseIdentifier": {
        "courtType": "HC",
        "cnr": "KAHC010123452024"
      },
      "identifierStatus": "CONFIRMED",
      "courtType": "HC",
      "court": "High Court of Karnataka",
      "state": "Karnataka",
      "district": null,
      "bench": null,
      "caseType": "WP",
      "caseTypeName": "Writ Petition",
      "caseNature": null,
      "caseNumber": "WP/12345/2024",
      "cnrNumber": "KAHC010123452024",
      "filingNumber": "WP/45120/2024",
      "registrationNumber": "WP/12345/2024",
      "filingDate": "2024-03-18",
      "filingYear": 2024,
      "registrationDate": "2024-03-21",
      "caseStatus": "Pending",
      "nextHearingDate": "2026-11-04",
      "decisionDate": null,
      "natureOfDisposal": null,
      "petitioner": "K. Ramesh Babu",
      "respondent": "The State of Karnataka, The Principal Secretary, Revenue Department, The Deputy Commissioner, Acme Logistics Pvt. Ltd, Indian Oil Corporation Ltd",
      "partyRole": "RESPONDENT",
      "matchedParty": "Acme Logistics Pvt. Ltd",
      "petitioners": [
        "K. Ramesh Babu"
      ],
      "respondents": [
        "The State of Karnataka",
        "The Principal Secretary, Revenue Department",
        "The Deputy Commissioner",
        "Acme Logistics Pvt. Ltd",
        "Indian Oil Corporation Ltd"
      ],
      "partyCountTruncated": false
    },
    {
      "caseRef": "cr_123e0077c97f23bc",
      "caseIdentifier": {
        "courtType": "DC",
        "cnr": "DLST010012342023"
      },
      "identifierStatus": "CONFIRMED",
      "courtType": "DC",
      "court": "Saket District Court, Delhi",
      "state": "Delhi",
      "district": "South Delhi",
      "bench": null,
      "caseType": "CS",
      "caseTypeName": "Civil Suit",
      "caseNature": null,
      "caseNumber": "1234/2023",
      "cnrNumber": "DLST010012342023",
      "filingNumber": "1234/2023",
      "registrationNumber": "1234/2023",
      "filingDate": "2023-06-02",
      "filingYear": 2023,
      "registrationDate": "2023-06-05",
      "caseStatus": "Disposed",
      "nextHearingDate": null,
      "decisionDate": "2025-01-29",
      "natureOfDisposal": "Decreed",
      "petitioner": "BLUELINE FREIGHT SERVICES",
      "respondent": "ACME LOGISTICS PRIVATE LIMITED",
      "partyRole": "RESPONDENT",
      "matchedParty": "ACME LOGISTICS PRIVATE LIMITED",
      "petitioners": [
        "BLUELINE FREIGHT SERVICES"
      ],
      "respondents": [
        "ACME LOGISTICS PRIVATE LIMITED"
      ],
      "partyCountTruncated": false
    },
    {
      "caseRef": "cr_42ec81178b2c1da7",
      "caseIdentifier": {
        "courtType": "ITAT",
        "establishmentCode": "MUMBAI",
        "caseType": "ITA",
        "registrationNumber": "2210/2022"
      },
      "identifierStatus": "CONFIRMED",
      "courtType": "ITAT",
      "court": "Income Tax Appellate Tribunal",
      "state": "Maharashtra",
      "district": null,
      "bench": "Mumbai",
      "caseType": "ITA",
      "caseTypeName": "Income Tax Appeal",
      "caseNature": "Civil",
      "caseNumber": "ITA 2210/MUM/2022",
      "cnrNumber": null,
      "filingNumber": null,
      "registrationNumber": "2210/2022",
      "filingDate": "2022-09-14",
      "filingYear": 2022,
      "registrationDate": null,
      "caseStatus": "Pending",
      "nextHearingDate": null,
      "decisionDate": null,
      "natureOfDisposal": null,
      "petitioner": "ACME LOGISTICS PRIVATE LIMITED",
      "respondent": "DCIT CIRCLE 4(1)",
      "partyRole": "PETITIONER",
      "matchedParty": "ACME LOGISTICS PRIVATE LIMITED",
      "petitioners": [
        "ACME LOGISTICS PRIVATE LIMITED"
      ],
      "respondents": [
        "DCIT CIRCLE 4(1)"
      ],
      "partyCountTruncated": false
    }
  ],
  "nextPageToken": "eyJzIjoiQ1BIUzBleGFtcGxlZGVtbzAwMDEiLCJwIjoxMDB9.0kQjJtYRBsIazMj45LlfiSe7R-ZlsjATarNBpOcql-w"
}
```

## Filters and options

These request fields control what the search looks for. Filters are fixed for the life of the search.

| Field | Values | Default |
| --- | --- | --- |
| `partyType` | `PETITIONER`, `RESPONDENT` or `BOTH` | `BOTH` |
| `filters.fromYear` | A year from 1950 to the current year, and not later than `toYear`. Cases filed in this year or later. | None |
| `filters.toYear` | A year from 1950 to the current year. Cases filed in this year or earlier. | None |
| `filters.caseStatus` | `ALL`, `PENDING` or `DISPOSED` | `ALL` |
| `filters.courtTypes` | Which courts to search: `SC` (Supreme Court), `HC` (High Courts), `DC` (District Courts) and `OTHER` (the consumer commissions, tribunals such as NCLT, NCLAT, CESTAT, ITAT, DRT, DRAT, GSTAT, NGT, SAT and APTEL, and any court that cannot be placed) | All courts |
| `filters.sortBy` | `filing_desc` (newest first) or `filing_asc` (oldest first), applied to the whole result set | `filing_desc` |
| `nameVariations` | Up to 25 other spellings of the name | None |
| `autoNameVariations` | `true` or `false`: generate further spellings of the name | `true` |
| `mode` | `SYNC` or `ASYNC`. Asynchronous mode is available on some plans. | `SYNC` |

## Paging and retries

- **Exactly 100 per page.** Every page has 100 cases except the last, and a short or empty page is never returned while more exist.
- **Safe to repeat.** Repeating a page request with the same token returns the same page again, so it is safe to retry.
- **Slow pages.** If a page cannot be assembled within 60 seconds you get `503` with `Retry-After`. Nothing is delivered, so retry with the same token.
- **Retention.** A search and its results are kept for 7 days. After that, requests return `410`.

## Errors

| Status | Code | Message |
| --- | --- | --- |
| 400 | 60405 | Real-time court search is only available for company entities - add cases for a person entity manually |
| 400 | 61453 | The page token is not valid for this search |
| 400 | 61454 | The search filters are not valid |
| 402 | 61455 | Your plan's search allowance has been used up |
| 403 | 61456 | No data source is enabled for this account |
| 403 | 61465 | Asynchronous collection is not available on your plan. Page through the results with a normal search instead |
| 404 | 61449 | This search was not found |
| 409 | 61451 | Another request on this search is still running. Wait for it to finish, then retry |
| 409 | 61467 | This search is still being collected. Its results can be read once its status is COMPLETE |
| 410 | 61450 | This search is older than its retention period and its results have been deleted. Start a new search |
| 429 | 61457 | Too many requests - slow down and retry after the indicated time |
| 429 | 61466 | Too many of your searches are still being collected. Wait for one to finish, then start another |
| 503 | 61452 | This page could not be assembled in time. Nothing was delivered or charged - retry with the same page token |

## Frequently asked questions

### Can I search for a person?

No. The Historical Cases Search API is for companies (entityType BUSINESS). A person search is refused. To watch a person, add them as a party with the Parties Watchlist API.

### How many cases does each call return?

100. The start call returns the first 100 cases, and each further page returns the next 100. The last page can be shorter.

### How do I get the rest of the results?

Pass the nextPageToken from the previous response as pageToken to the results endpoint. You have reached the end when nextPageToken is null and the status is COMPLETE.

### How long are results kept?

7 days. After that the search and its results are deleted and requests return 410. Start a new search to get fresh results.

### What if a page takes too long?

If a page cannot be assembled within 60 seconds, the call returns 503 with a Retry-After header and nothing is delivered. Retry with the same token.

### Is this the same as monitoring?

No. A history search is a one-time look at a company's past cases. To be alerted when new cases are filed, add the company as a party with the Parties Watchlist API.
