CasePrimus.aiby Attestr
Documentation menu
APIv1Updated 15 October 2026

Company Litigation History Search API

View as Markdown

API To Search A Company's Court-Case History Across Indian Courts

The Company Litigation History Search API returns the court cases a company has been involved in, without adding it to a watchlist. 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. See Trust & Compliance.

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

    Page through the rest

    Send the nextPageToken as pageToken to GET /historical-search/{searchId}/results for the next 100.

  3. 3

    Stop at the end

    The history is complete when nextPageToken is null and the status is COMPLETE.

API definition

Send your API key in the X-CasePrimus-Api-Key header. See Authentication, and Rate limits & errors.

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. Requires historicalSearch.read.

Request URL

GEThttps://api.caseprimus.ai/api/caseprimus/v1/historical-search/{searchId}/results

Request headers

TypeNameValue / descriptionOptional
StringX-CasePrimus-Api-KeyYour API key: {apiKey}Required

No API key yet? See Authentication.

Path and query parameters

NameInRequiredDescription
searchIdpathRequiredThe searchId returned when the search was started.
pageTokenqueryOptionalThe 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

Request
BASE="https://api.caseprimus.ai/api/caseprimus/v1"

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

Responses

200The page.
400Invalid page token (a token from another search, altered, or beyond what has been delivered).
402The plan's search allowance is used up.
404Unknown or deleted search.
409Another request on this search is still running.
410The search has expired and its results were deleted.
429Too many requests for this account. See Retry-After.
503The page could not be assembled in time. Retry with the same token.

Response fields (HTTP 200)

FieldDescription
searchId
string

The id of this search. Use it to read further pages.

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

The company name that was searched for.

partyType
enum
PETITIONERRESPONDENTBOTH
filters
object

The filters the search was started with.

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
code
enum
RESULT_CAP_REACHEDSOURCE_UNAVAILABLE
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.

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

The court the case is in.

state
string or null

The state the court is in.

district
string or null

The district, for courts that have one.

bench
string or null

The bench, for courts that have benches.

caseType
string or null

The court's short code for the type of case, for example WP.

caseTypeName
string or null

The full name of the case type, for example Writ Petition.

caseNature
string or null

The nature of the case, for example Civil.

caseNumber
string or null

The case number as the court writes it.

cnrNumber
string or null

Null when the case has no customer-visible CNR.

filingNumber
string or null

The number the case was filed under.

registrationNumber
string or null

The number the case was registered under.

filingDate
string or null

YYYY-MM-DD.

filingYear
integer or null

The year the case was filed.

registrationDate
string or null

The date the case was registered.

caseStatus
string or null

The case's status, for example PENDING.

nextHearingDate
string or null

The date of the next hearing, if one is set.

decisionDate
string or null

The date of the decision, for a decided case.

natureOfDisposal
string or null

How the case was disposed of, for a decided case.

petitioner
string or null

The petitioner named for the case.

respondent
string or null

The respondent named for the case.

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"
}

Filters and options

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

FieldValuesDefault
partyTypePETITIONER, RESPONDENT or BOTHBOTH
filters.fromYearA year, 1950 or later. Cases filed in this year or later.None
filters.toYearA year, 1950 or later. Cases filed in this year or earlier.None
filters.caseStatusALL, PENDING or DISPOSEDALL
nameVariationsUp to 25 other spellings of the nameNone
autoNameVariationstrue or false: generate further spellings of the nametrue
modeSYNC 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

Errors use the HTTP status and a JSON body with a stable numeric code. These are the errors documented for the Company Litigation History Search API. The full format, and the limits that apply to every call, are on Rate limits & errors.

StatusCodeMessage
40060405Real-time court search is only available for company entities - add cases for a person entity manually
40061453The page token is not valid for this search
40061454The search filters are not valid
40261455Your plan's search allowance has been used up
40361456No data source is enabled for this account
40361465Asynchronous collection is not available on your plan. Page through the results with a normal search instead
40461449This search was not found
40961451Another request on this search is still running. Wait for it to finish, then retry
40961467This search is still being collected. Its results can be read once its status is COMPLETE
41061450This search is older than its retention period and its results have been deleted. Start a new search
42961457Too many requests - slow down and retry after the indicated time
42961466Too many of your searches are still being collected. Wait for one to finish, then start another
50361452This 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 Company Litigation History Search API is for companies (entityType BUSINESS). A person search is refused. To monitor a person, use the Litigation 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 to a watchlist with the Litigation Watchlist API.

Related

API

Litigation Watchlist API

Monitor companies and people for new court cases, with daily checks and alerts.

API

Court Case Lookup API

Look up any case by CNR or case number, and download its orders.

API

AI Case Summary API

Get a plain-language summary and risk level for a case, order by order.

Authentication

Create an API key, and optionally sign and encrypt requests.

Rate limits & errors

How requests are counted, and every error code.

Webhooks

Get alerts pushed to your own endpoint, signed and retried.

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
← PreviousAI Case Summary API

Last updated 15 October 2026