CasePrimus.aiby Attestr
Documentation menu
POST/historical-search

Start a historical search

Starts a search for a company and returns its first page in the same call: exactly 100 cases (fewer only when that is all there is), a `searchId`, and a `nextPageToken` (null when there is nothing more).

Overview

Starts a search for a company and returns its first page in the same call: exactly 100 cases (fewer only when that is all there is), a searchId, and a nextPageToken (null when there is nothing more). Requires historicalSearch.write.

Order: newest filing date first from the primary source; further cases that source did not return follow. A case found by both sources is returned once.

If the page cannot be assembled within 60 seconds the call returns 503 with Retry-After; the error details carry the searchId and a nextPageToken to carry on with. Nothing is delivered or charged in that case. The same clientReference with the same request within 24 hours returns the same search and first page again without a new charge.

Limited to the account's requests per minute (default 60): over it, 429 with Retry-After and X-RateLimit-* headers.

Asynchronous mode. Send "mode": "ASYNC" to have the whole result set collected in the background instead of paging it yourself - for when you want everything in one go. The call returns 202 straight away with the searchId and status: RUNNING; no results yet. When the search finishes its status becomes COMPLETE (everything the sources could give, up to the results-per-search cap of your plan) or FAILED (nothing is stored and nothing is charged - start it again). Find out by polling GET /historical-search/{searchId} or, better, by subscribing a webhook to historical_search.finished. Once COMPLETE, read the results page by page (GET /historical-search/{searchId}/results, first page = no token) or download them as one JSON file (GET /historical-search/{searchId}/download). Reading is free: an asynchronous search is billed once, when it completes, and a failed one is never billed. Results and file are kept for 7 days from completion. Available on per-search plans (or when your plan has it switched on); at most 3 asynchronous searches collect at once per account. DELETE on a running search cancels it.

Auth API keyContent-Type application/json
Send your API key in the X-CasePrimus-Api-Key header. See Authentication for how to create a key, and Rate limits & errors for how requests are counted.

Request body

FieldDescription
name
string
Required

The company's name.

2 to 255 characters

entityType
enum
Optional

BUSINESS only. A person is refused with PERSON_SEARCH_NOT_SUPPORTED.

BUSINESS
registrationNumber
string or null
Optional

Optional, e.g. CIN. Sharpens matching.

up to 64 characters

location
string or null
Optional

Optional address. Sharpens matching.

nameVariations
array of string
Optional

Other spellings of the name. Added to any generated ones.

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.

PETITIONERRESPONDENTBOTH
filters
object
Optional

Fixed for the life of the search. Applied by the data sources, so a narrower search costs less.

fromYear
integer or null
Optional

Cases filed in this year or later.

minimum 1950

toYear
integer or null
Optional

Cases filed in this year or earlier.

minimum 1950

caseStatus
enum
Optional
ALLPENDINGDISPOSED
clientReference
string
Optional

Your own reference. Also makes a repeated start call safe to retry.

up 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.

SYNCASYNC
Body: First page (3 of the 100 results shown)
{
  "name": "Acme Logistics Private Limited",
  "entityType": "BUSINESS",
  "registrationNumber": "U63090MH2012PTC123456",
  "partyType": "BOTH",
  "filters": {
    "caseStatus": "ALL"
  },
  "clientReference": "vendor-onboarding-4821"
}

Example request

Replace CASEPRIMUS_API_KEY with your key.

Request
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

200The first page (mode SYNC).
FieldDescription
searchId
string
mode
enum

ASYNC: collected in the background (see POST /historical-search).

SYNCASYNC
status
enum

SYNC searches are ACTIVE, COMPLETE or EXPIRED. ASYNC searches are RUNNING, COMPLETE, FAILED or EXPIRED.

ACTIVECOMPLETEEXPIREDRUNNINGFAILED
name
string
partyType
enum
PETITIONERRESPONDENTBOTH
filters
object
clientReference
string or null
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
code
enum
RESULT_CAP_REACHEDSOURCE_UNAVAILABLE
message
string
createdAt
integer

Epoch ms.

expiresAt
integer

Epoch ms. Results are deleted at this time.

pageSize
integer
results
array of object
caseRef
string

Stable id of the case: the same case has the same caseRef in every search.

caseIdentifier
object or null

What identifies the case for a live lookup. Null when it cannot be established without a live check.

identifierStatus
enum
CONFIRMEDNEEDS_CONFIRMATION
courtType
string

DC, HC, SC, CC, NCLT, NCLAT, CESTAT, DRT, DRAT, GSTAT, ITAT, APTEL, NGT, SAT or OTHER.

court
string or null
state
string or null
district
string or null
bench
string or null
caseType
string or null
caseTypeName
string or null
caseNature
string or null
caseNumber
string or null
cnrNumber
string or null

Null when the case has no customer-visible CNR.

filingNumber
string or null
registrationNumber
string or null
filingDate
string or null

YYYY-MM-DD.

filingYear
integer or null
registrationDate
string or null
caseStatus
string or null
nextHearingDate
string or null
decisionDate
string or null
natureOfDisposal
string or null
petitioner
string or null
respondent
string or null
partyRole
enum or null

The side the searched company is on.

PETITIONERRESPONDENTBOTH
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.

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`.

respondents
array of string

Every respondent, each once, in the court's order. At most 25 - see `partyCountTruncated`.

partyCountTruncated
boolean

True when either list was cut at 25. `matchedParty` is still named.

nextPageToken
string or null

Pass it to get the next page. Null when there is nothing more.

Response 200
{
  "searchId": "CPHS0exampledemo0001",
  "mode": "SYNC",
  "status": "ACTIVE",
  "name": "Acme Logistics Private Limited",
  "partyType": "BOTH",
  "filters": {
    "caseStatus": "ALL"
  },
  "clientReference": "vendor-onboarding-4821",
  "delivered": 100,
  "warnings": [],
  "createdAt": 1791600000000,
  "expiresAt": 1792204800000,
  "pageSize": 100,
  "results": [
    {
      "caseRef": "CR0hc7f3a91e",
      "caseIdentifier": {
        "courtType": "HC",
        "cnr": "KAHC010123452024"
      },
      "identifierStatus": "CONFIRMED",
      "courtType": "HC",
      "court": "High Court of Karnataka",
      "state": "Karnataka",
      "district": null,
      "bench": "Bengaluru",
      "caseType": "WP",
      "caseTypeName": "Writ Petition",
      "caseNature": "Civil",
      "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",
      "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": "CR0dc21b5c07",
      "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 (Commercial)",
      "caseNature": "Civil",
      "caseNumber": "CS/1234/2023",
      "cnrNumber": "DLST010012342023",
      "filingNumber": "1234/2023",
      "registrationNumber": "CS/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": "CR0it88e0d412",
      "caseIdentifier": null,
      "identifierStatus": "NEEDS_CONFIRMATION",
      "courtType": "ITAT",
      "court": "Income Tax Appellate Tribunal, Mumbai",
      "state": "Maharashtra",
      "district": null,
      "bench": "Mumbai",
      "caseType": "ITA",
      "caseTypeName": "Income Tax Appeal",
      "caseNature": "Tax",
      "caseNumber": "ITA/2210/MUM/2022",
      "cnrNumber": null,
      "filingNumber": null,
      "registrationNumber": null,
      "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": "eyJzIjoiQ1BIUzBzYW5kYm94ZGVtbzAwMDEiLCJwIjoxMDB9.Qk3x9Wf2mT8aYb1c"
}
202Accepted (mode ASYNC). The search is RUNNING; there are no results yet.
FieldDescription
searchId
string
mode
enum

ASYNC: collected in the background (see POST /historical-search).

SYNCASYNC
status
enum

SYNC searches are ACTIVE, COMPLETE or EXPIRED. ASYNC searches are RUNNING, COMPLETE, FAILED or EXPIRED.

ACTIVECOMPLETEEXPIREDRUNNINGFAILED
name
string
partyType
enum
PETITIONERRESPONDENTBOTH
filters
object
clientReference
string or null
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
code
enum
RESULT_CAP_REACHEDSOURCE_UNAVAILABLE
message
string
createdAt
integer

Epoch ms.

expiresAt
integer

Epoch ms. Results are deleted at this time.

Response 202
{
  "searchId": "CPHS0exampleasync01",
  "mode": "ASYNC",
  "status": "RUNNING",
  "name": "Acme Logistics Private Limited",
  "partyType": "BOTH",
  "filters": {
    "caseStatus": "ALL"
  },
  "clientReference": "vendor-onboarding-4821",
  "delivered": 0,
  "warnings": [],
  "createdAt": 1791936000000,
  "expiresAt": 1792566000000,
  "collected": 0,
  "completedAt": null
}
400Invalid input, filters or party type, or a person search.
Response 400
{
  "httpStatusCode": 400,
  "code": 60405,
  "message": "Real-time court search is only available for company entities - add cases for a person entity manually",
  "appError": true
}
402The plan's search allowance is used up.
Response 402
{
  "httpStatusCode": 402,
  "code": 61455,
  "message": "Your plan's search allowance has been used up",
  "appError": true
}
403Caller lacks historicalSearch.write, or (mode ASYNC) asynchronous collection is not available on the plan.
Response 403
{
  "httpStatusCode": 403,
  "code": 61465,
  "message": "Asynchronous collection is not available on your plan. Page through the results with a normal search instead",
  "appError": true
}
429Too many requests for this account, or (mode ASYNC) too many asynchronous searches still collecting. See `Retry-After`.
Response 429
{
  "httpStatusCode": 429,
  "code": 61466,
  "message": "Too many of your searches are still being collected. Wait for one to finish, then start another",
  "appError": true,
  "details": {
    "retryAfterSeconds": 60
  }
}
503The page could not be assembled in time. Retry; nothing was delivered or charged.
Response 503
{
  "httpStatusCode": 503,
  "code": 61452,
  "message": "This page could not be assembled in time. Nothing was delivered or charged - retry with the same page token",
  "appError": true,
  "details": {
    "retryAfterSeconds": 3,
    "searchId": "CPHS0exampledemo0001",
    "nextPageToken": "eyJzIjoiQ1BIUzBzYW5kYm94ZGVtbzAwMDEiLCJwIjowfQ.Zm2p0Lr7Vx5nEa9d"
  }
}

Error responses share one shape, listed on Rate limits & errors.

Related

Webhook event

historical_search.finished

An asynchronous historical search has finished collecting: its status is COMPLETE (the results can be read and downloaded) or FAILED (nothing is charged - start it again; `failureReason` says why).

Previous in Historical Search

List recent searches

Next in Historical Search

Status of a search

All endpoints

Historical Search API

Need API access?

Bring a few of the Indian customers, vendors or partners you work with. We'll set you up with a key and show you what monitoring surfaces in week one.

Request a Demo

Last updated 14 October 2026