# Court Case Lookup API

Source: https://caseprimus.ai/docs/court-case-lookup-api

## API To Look Up Any Indian Court Case By CNR Or Case Number

The **Court Case Lookup API** retrieves the details of a single case in an Indian court or tribunal on demand, using its CNR or case number. Built for due diligence, onboarding and contract review, it answers the moment a name or a case comes up, without adding anything to a watchlist.

The response includes the parties, court, stage, filing date and every order on the case. Each order carries an `orderId` you can use to download that order's document, and the lookup returns a `searchId` you can use to request an AI summary of the case.

> **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

- **Lookup by CNR or case number.** Send the `cnr` where you have it. For other cases, identify the case by court type, registration number, case type and bench or tribunal code.
- **All major courts and tribunals.** District Courts, High Courts, the Supreme Court, Consumer Commissions, NCLT, NCLAT, GSTAT, DRT, DRAT and CESTAT.
- **Full case details.** Parties, court, stage, filing date and every order on the case, in one response.
- **Order documents on demand.** Download any order's document through a signed link that expires after 5 minutes. Each page carries a CasePrimus provenance strip, and the document is not a certified copy.
- **AI summary built in.** Every lookup returns a `searchId` for the AI Case Summary API, and `latestSummary` holds the most recent summary generated for the case.
- **No watchlist needed.** A lookup is one-time and on demand. It is not tied to a watchlist entity and starts no monitoring.

## How it works

1. **Send the case identifier.** Post a `caseIdentifier` with the court type and the CNR or case number to `POST /case-lookup`.
2. **Receive the case.** You get the parties, court, stage, filing date and orders, plus a `searchId` and an `orderId` for every order.
3. **Download an order or summarize.** Use the `searchId` and an `orderId` to download an order's document, or use the `searchId` to request an AI summary.

## API definition

### Look up a case by its identifier

Looks up a single case once, on demand, by its case number or CNR. It is not tied to a watchlist entity and starts no monitoring. The identifier fields you must send depend on courtType. Every order on the case comes back with an orderId: pass it to the order download endpoint to get that order's document. The response also carries a searchId, which you use to download orders or request an AI summary without repeating the lookup, and latestSummary, the most recent AI summary generated for the case (null if there is none). Requires case.write.

**Request URL**

`POST https://api.caseprimus.ai/api/caseprimus/v1/case-lookup`

**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 |
| --- | --- | --- | --- |
| `caseIdentifier` | object | Required |  |
| `caseIdentifier.courtType` | enum | Required | One of: DC, SC, HC, CC, NCLT, NCLAT, GSTAT, DRT, DRAT, CESTAT |
| `caseIdentifier.cnr` | string | Optional | DC, SC, HC only. |
| `caseIdentifier.registrationNumber` | string | Optional | Format depends on courtType - see the description above. |
| `caseIdentifier.filingNumber` | string | Optional | NCLT/NCLAT/GSTAT only. |
| `caseIdentifier.diaryNumber` | string | Optional | SC, DRT, DRAT, CESTAT only. |
| `caseIdentifier.establishmentCode` | string | Optional | Bench/tribunal code - required for HC (when not using cnr) and every tribunal court type. |
| `caseIdentifier.caseType` | string | Optional | Required alongside registrationNumber for most court types. The valid values depend on courtType. |

**Sample request**

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

curl -X POST "$BASE/case-lookup" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caseIdentifier": {
      "courtType": "DC",
      "cnr": "DLCT010012342020"
    }
  }'
```

**Responses**

- `200`: Case details found.
- `400`: Malformed caseIdentifier for the given courtType.
- `403`: Caller lacks the case.write permission.
- `500`: The underlying case lookup failed.

**Example response (200)**

```json
{
  "searchId": "CPCSH0exampledemo0001",
  "latestSummary": null,
  "cnr": "DLCT010012342020",
  "courtType": "DC",
  "parties": {
    "petitioner": "Acme Traders Pvt Ltd",
    "respondent": "Jane Doe"
  },
  "court": "District Court, Delhi",
  "stage": "Arguments",
  "filingDate": "10-01-2020",
  "orders": [
    {
      "orderId": "a1b2c3d4e5f6",
      "number": "3",
      "orderDate": "16-05-2017",
      "judge": "Hon'ble Judge Example",
      "orderType": null,
      "attachment": null
    }
  ]
}
```

### Download Case Order

Returns a link to one order's document. Send the searchId from a previous case lookup and the orderId from that response's orders list. The url is a signed link that expires after 5 minutes and is generated fresh on every call, so do not store it. The document is the court's order with a CasePrimus provenance strip down the left margin of every page; it is not a certified copy. District Court orders, and orders you already downloaded, answer at once. For other courts the call waits for the download for up to 55 seconds. If it is still running you get 503 ORDER_DOWNLOAD_NOT_READY with a Retry-After header; send the same request again and it joins the download already in progress. Requires case.write.

**Request URL**

`POST https://api.caseprimus.ai/api/caseprimus/v1/case-lookup/orders/download`

**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 |
| --- | --- | --- | --- |
| `searchId` | string | Required | The searchId returned by the case lookup. |
| `orderId` | string | Required | The orderId of the order, from the lookup's orders list. |

**Sample request**

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

curl -X POST "$BASE/case-lookup/orders/download" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searchId": "CPCSH0exampledemo0001",
    "orderId": "a1b2c3d4e5f6"
  }'
```

**Responses**

- `200`: The order's document.
- `400`: Malformed input, this search record does not exist, or this court's orders cannot be downloaded right now.
- `403`: Caller lacks the case.write permission.
- `404`: The orderId is not one of this case's orders.
- `422`: The court has no document for this order (`details.reason`).
- `503`: Still being downloaded after 55 seconds. Send the same request again (`Retry-After`).

**Response fields (HTTP 200)**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `orderId` | string |  |  |
| `url` | string |  | Signed link, valid for 5 minutes. Never store it. |

**Example response (200)**

```json
{
  "orderId": "a1b2c3d4e5f6",
  "url": "https://files.example.com/dlct010012342020-9f8e7d6c5b4a.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=..."
}
```

## Court types

Set `courtType` to one of these codes. Send the `cnr` for District Courts, the Supreme Court and High Courts where you have it.

| Code | Court or tribunal |
| --- | --- |
| SC | Supreme Court of India |
| HC | High Courts |
| DC | District Courts |
| CC | Consumer Commissions |
| NCLT | National Company Law Tribunal |
| NCLAT | National Company Law Appellate Tribunal |
| DRT | Debts Recovery Tribunals |
| DRAT | Debts Recovery Appellate Tribunals |
| GSTAT | Goods and Services Tax Appellate Tribunal |
| CESTAT | Customs, Excise and Service Tax Appellate Tribunal |

## How order downloads behave

- **Short-lived links.** The `url` is a signed link that expires after 5 minutes and is generated fresh on every call, so do not store it.
- **Provenance on every page.** The document is the court's order with a CasePrimus strip down the left margin of every page. It is not a certified copy.
- **District Court orders are immediate.** District Court orders, and orders you have already downloaded, answer at once.
- **Other courts can take longer.** For other courts the call waits for the download for up to 55 seconds. If it is still running you get `503` with `Retry-After`; send the same request again and it joins the download already in progress.

## Errors

| Status | Code | Message |
| --- | --- | --- |
| 400 | 60436 | This search record does not exist |
| 404 | 60434 | No matching order was found for the number and date provided |
| 422 | 60433 | Could not download this order right now, please try again shortly |
| 500 | 60406 | Could not look up this case right now, please try again shortly |
| 503 | 61469 | This order is still being downloaded from the court. Send the same request again in a few seconds - nothing is charged until it is delivered |

## Frequently asked questions

### What is a CNR?

A CNR is a 16-character code that identifies a case in India's eCourts system. If you have it, it is the quickest way to look a case up for District Courts, the Supreme Court and High Courts.

### Does a lookup add the case to a watchlist?

No. A lookup is one-time and on demand. It is not tied to a watchlist entity and starts no monitoring. Use the Litigation Watchlist API to monitor a company or person.

### Can I download the court's order?

Yes. Send the searchId from the lookup and the orderId of the order to the order download endpoint. You get a signed link that expires after 5 minutes. The document carries a CasePrimus provenance strip and is not a certified copy.

### How long does an order download take?

District Court orders, and orders you already downloaded, answer at once. For other courts the call waits up to 55 seconds. If the download is still running you get a 503 with a Retry-After header; send the same request again.

### Which courts and tribunals are covered?

District Courts, High Courts, the Supreme Court, Consumer Commissions, and the NCLT, NCLAT, GSTAT, DRT, DRAT and CESTAT tribunals.

### Can I get an AI summary of the case?

Yes. Use the searchId from the lookup with the AI Case Summary API. The most recent summary is also returned as latestSummary on the lookup.