CasePrimus.aiby Attestr
Documentation menu
APIv1Updated 14 November 2026

Live Case Lookup API

API To Look Up Any Indian Court Case By CNR Or Case Number, And Summarize It With AI

The Live 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 download every order as one zip, or to request an AI summary: a plain-language summary of the case with a risk level and the reasoning behind it.

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

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, and the NCLT, NCLAT, GSTAT, DRT, DRAT, CESTAT, NGT, SAT, ITAT and APTEL tribunals.

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.

All orders as one zip

Download every order of a case as a single zip: start the bundle, then poll it until it is ready.

An AI summary in plain language

Request a summary of the case, with a risk level, the reasoning behind it, and a summary of every order.

No watchlist needed

A lookup is one-time and on demand. It starts no monitoring and needs no party.

Refresh on demand

Looking up the same case again refreshes it and returns the same searchId.

How it works

  1. 1

    Send the case identifier

    Post a caseIdentifier with the court type and the CNR or case number to POST /case-lookup.

  2. 2

    Receive the case

    You get the parties, court, stage, filing date and orders, plus a searchId and an orderId for every order.

  3. 3

    Download the orders

    Use the searchId and an orderId to download an order's document, or the searchId alone to download every order as one zip.

  4. 4

    Ask for an AI summary

    Send the searchId to POST /case-lookup/summarize, then poll GET /case-lookup/summarize/{id} until the status is COMPLETE.

API definition

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

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). An order's attachment is always null in this response: the document comes from the order download endpoint. Looking up the same case again refreshes it and returns the same searchId. If the court has no such case you get 404 CASE_NOT_FOUND_AT_COURT and nothing is charged; if the reference matches more than one case you get 400 with code 4003. Requires case.write.

Request URL

POSThttps://api.caseprimus.ai/api/caseprimus/v1/case-lookup

Request headers

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

No API key yet? See Authentication.

Input parameters

FieldDescription
caseIdentifier
object
Required

Identifies one case. Which other fields you send depends on courtType - send exactly one of the alternatives listed for it.

DC: cnr.

SC: cnr, or caseType + registrationNumber, or diaryNumber.

HC: cnr, or establishmentCode + caseType + registrationNumber.

CC (consumer commission): registrationNumber (the e-Jagriti case number) only.

NCLT, NCLAT, GSTAT: establishmentCode + filingNumber, or establishmentCode + caseType + registrationNumber.

DRT, DRAT: establishmentCode + diaryNumber, or establishmentCode + caseType + registrationNumber.

CESTAT: establishmentCode + diaryNumber, or establishmentCode + caseType + registrationNumber.

NGT: establishmentCode (PB, EZ, CZ, WZ or SZ) + either caseType (OA, RA, MA, AP, EA, IA or TA) + registrationNumber (n/yyyy), or diaryNumber (the 12-digit diary number / year).

SAT: establishmentCode (MUM) + either caseType (SEBI, IRDAI or PFRDA) + registrationNumber (the Appeal No., n/yyyy, at most 4 digits before the year), or filingNumber (the AL No. - Appeal Lodging number, n/yyyy).

ITAT: establishmentCode (the bench's city in capitals, for example DELHI, MUMBAI or BANGALORE; Cochin is ERNAKULAM and Visakhapatnam is VISHAKHAPATNAM) + caseType (ITA, CO, ITSSA, ITTPA, ITITA, WTA, BMA, GTA, SA or MA) + registrationNumber (the Appeal No. and filing year, n/yyyy, at most 5 digits before the year); all three are required.

APTEL: establishmentCode (DEL) + either caseType (APL, OP, EP, RP or CP) + registrationNumber (the Case No., n/yyyy), or diaryNumber (the DFR No., n/yyyy). The DFR number is the tribunal's diary number and every case has one from the day it is filed; a Case No. is allotted only on registration, so a recently filed case may be reachable by its DFR number alone. Note that the year means different things on the two: with a Case No. it is the year the case was registered, with a DFR No. the year it was filed, and for the same case these can differ.

courtType
enum
Required
DCSCHCCCNCLTNCLATGSTATDRTDRATCESTATNGTSATITATAPTEL
cnr
string
Optional

DC, SC, HC only.

registrationNumber
string
Optional

Format depends on courtType - see the description above. Usually number/year (for example 87/2018; at most 4 digits for SAT, 5 for ITAT); for HC the number/year is sent with caseType, and for CC it is the whole e-Jagriti case number.

filingNumber
string
Optional

NCLT/NCLAT/GSTAT only, and SAT (the AL No. - Appeal Lodging number - n/yyyy).

diaryNumber
string
Optional

SC, DRT, DRAT, CESTAT, NGT (the 12-digit diary number / year, e.g. 070111601768/2026) and APTEL (the DFR No., n/yyyy).

establishmentCode
string
Optional

Bench/tribunal code - required for HC (when not using cnr) and every tribunal court type. NGT: PB, EZ, CZ, WZ or SZ. SAT: MUM. APTEL: DEL. ITAT: the bench's city in capitals (DELHI, MUMBAI, BANGALORE ...; Cochin is ERNAKULAM, Visakhapatnam is VISHAKHAPATNAM).

caseType
string
Optional

Required alongside registrationNumber for most court types. The valid values depend on courtType, for example NGT: OA, RA, MA, AP, EA, IA, TA; SAT: SEBI, IRDAI, PFRDA; APTEL: APL, OP, EP, RP, CP; ITAT: ITA, CO, ITSSA, ITTPA, ITITA, WTA, BMA, GTA, SA, MA.

Sample request

Request
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": "HRFB010051662020"
    }
  }'

Responses

200Case details found. The same shape for every court type (a common core plus a few court-specific fields), with a top-level searchId, latestSummary (nullable) and an orderId on every order.
400Malformed caseIdentifier for the given courtType (60001, or the court's own code such as 4006 for a malformed CNR), or the reference matches more than one case (code 4003, nothing is stored or charged - make the identifier more specific).
403Caller lacks the case.write permission, or a free-trial account has used its lookup allowance (FREE_PLAN_USAGE_LIMIT_EXCEEDED, 61443).
404The court has no case for this reference (CASE_NOT_FOUND_AT_COURT, 60438). Nothing is stored and nothing is charged.
500The case lookup failed at the court or in transit (CASE_LOOKUP_FAILED, 60406). Try again shortly.

Response fields (HTTP 200)

FieldDescription
searchId
string

The id of this stored lookup. Use it to download orders, request an AI summary, or read the case back later without a new lookup.

latestSummary
object

The most recent AI summary generated for a case (see POST /case-lookup/summarize). A refresh of the case does not clear it.

_id
string

The id of the summary request.

status
enum
PENDINGCOMPLETEFAILED
riskLevel
enum or null
VERY_HIGHHIGHMODERATELOWUNCLASSIFIED
caseSummary
string or null
riskJustification
string or null
orderSummaries
array of object
error
string or null
generatedAt
integer

Epoch ms when this summary was requested.

caseType
string or null

The case type as the court names it (for example APP - APPLICATION, Appeal, Income Tax Appeal).

filingNumber
string or null
filingDate
string or null
filingYear
string or null

Four-digit year, as a string.

registrationNumber
string or null
registrationDate
string or null
cnrNumber
string or null

Null when the court has no CNR or it is not exposed (for example consumer commissions, NGT, SAT, ITAT and APTEL).

state
string or null
district
string or null
courtName
string or null
courtNumberAndJudge
string or null
courtEstablishment
string or null

The court establishment (District Court) or the bench / establishment code (tribunals, for example PB, MUM, DELHI).

firstHearingDate
string or null
nextHearingDate
string or null
previousHearingDate
string or null
caseStage
string or null
decisionDate
string or null
natureOfDisposal
string or null
caseStatus
string or null

As the court writes it: District Court says for example Case Disposed; NGT, SAT and ITAT give PENDING or DISPOSED. APTEL gives PENDING or DISPOSED, and also Defective - a filing on its DFR register whose papers the registry has not accepted, which is neither pending nor disposed.

coram
string or null
judicial
string or null
causeListName
string or null
bench
string or null
shortOrder
string or null
petitioners
array of object or null
petitionerName
string
petitionerCounsel
string or null
petitionerAddress
string or null

Tribunals only (NGT, SAT, ITAT, CESTAT); absent for other courts, and always null for APTEL, which publishes no party addresses.

petitionersText
string or null

The petitioners as one line of text (District Court: the court's own multi-line list).

respondents
array of object or null
respondentName
string
respondentCounsel
string or null
respondentAddress
string or null

Tribunals only (NGT, SAT, ITAT, CESTAT); absent for other courts, and always null for APTEL, which publishes no party addresses.

respondentsText
string or null
acts
array of object or null
act
string
sections
string or null
interlocutoryApplicationDetails
array of object or null

Interlocutory applications. District Court gives number, party, filingDate, nextDate, status and particulars; tribunals give number, caseNumber, party, filingDate, nextDate, status, particulars and (as the court provides them) filingNumber or disposalDate.

number
string or null
caseNumber
string or null
party
string or null
filingDate
string or null
nextDate
string or null
status
string or null
particulars
string or null
filingNumber
string or null
disposalDate
string or null
caseHistory
array of object or null

The hearing history, newest first for tribunals.

reg
any

District Court: the registration number of the case at that hearing (a string). Tribunals: the entry's position (an integer, 0 for the latest).

causeListType
string or null
judge
string or null
purpose
string or null
nextHearingDate
string or null
businessDate
string or null
businessDescription
string or null

Tribunals only.

adjournmentReason
string or null

Tribunals only.

orders
array of object
number
string or null

The order's number or reference as the court gives it.

orderDate
string or null

As the court writes it, usually DD-MM-YYYY.

judge
string or null
attachment
string or null

Always null on a lookup: the court's own link is never exposed - use POST /case-lookup/orders/download. Reading the stored case back returns a short-lived download link here (valid for 300 seconds), only for an order you already downloaded.

orderType
string or null
result
string or null

ITAT only: the outcome recorded for the order (for example Dismissed). Absent for other courts.

orderId
string

Stable for this stored lookup. Pass it, with the searchId, to POST /case-lookup/orders/download.

downloadedAt
integer or null

Epoch ms when the order's document was first downloaded. Null for an order not downloaded yet, and always null on POST /case-lookup.

objections
array of object or null

Filing objections raised by the registry, where the court publishes them (null otherwise).

number
string or null
objection
string or null
scrutinyDate
string or null
complianceDate
string or null
receiptDate
string or null
category
string or null

District Court only.

subCategory
string or null

District Court only.

subSubCategory
string or null

District Court only.

fir
object or null

District Court only: the FIR the case arises from, when it has one.

state
string or null
district
string or null
policeStation
string or null
number
string or null
year
string or null
earlierCourts
array of object or null

District Court only: the lower court the case came from.

courtNumberAndName
string or null
caseNumberAndYear
string or null
state
string or null
district
string or null
documents
array of object or null

District Court only: documents filed in the case.

docNumber
string or null
docName
string or null
advocate
string or null
receivingDate
string or null
filedBy
string or null
linkedCases
array of object or null

District Court only: cases linked to this one.

filingNumber
string or null
caseNumber
string or null
petitioner
string or null
respondent
string or null
status
string or null
statusDescription
string or null
transfers
array of object or null

District Court only: transfers between courts (an empty array if there are none). Absent or null for other courts.

reg
string or null
transferred
string or null
from
string or null
to
string or null
impugnType
string or null

Tribunals only: the type of the order appealed against. Absent for other courts.

impugnNumber
string or null

Tribunals only: the number of the order appealed against.

impugnDate
string or null

Tribunals only: the date of the order appealed against.

partyName
string or null

NGT only: the case title (the parties as one line).

assessmentYear
string or null

ITAT only: the assessment year, for example 2017-18.

Response 200
{
  "searchId": "CPCSH0exampledemo0001",
  "latestSummary": null,
  "caseType": "APP - APPLICATION",
  "filingNumber": "1821/2020",
  "filingDate": "08-07-2020",
  "filingYear": "2020",
  "registrationNumber": "135/2020",
  "registrationDate": "09-07-2020",
  "cnrNumber": "HRFB010051662020",
  "state": "Haryana",
  "district": "Faridabad",
  "courtName": "District and Sessions Courts, Faridabad",
  "courtNumberAndJudge": "1-District and Sessions Judge",
  "courtEstablishment": "District and Sessions Court, Faridabad",
  "firstHearingDate": "09-July-2020",
  "nextHearingDate": null,
  "previousHearingDate": null,
  "caseStage": null,
  "decisionDate": "27-October-2020",
  "natureOfDisposal": "Uncontested - DISMISSED AS WITHDRAWN",
  "caseStatus": "Case Disposed",
  "coram": null,
  "judicial": null,
  "causeListName": null,
  "bench": null,
  "shortOrder": null,
  "petitioners": [
    {
      "petitionerName": "Acme Traders Pvt Ltd",
      "petitionerCounsel": "Advocate - Advocate A"
    }
  ],
  "petitionersText": "1) Acme Traders Pvt Ltd\n                 Advocate - Advocate A",
  "respondents": [
    {
      "respondentName": "Jane Doe Realty Ltd",
      "respondentCounsel": null
    }
  ],
  "respondentsText": "1) Jane Doe Realty Ltd",
  "acts": [
    {
      "act": "CODE OF CIVIL PROCEDURE",
      "sections": "APP"
    }
  ],
  "interlocutoryApplicationDetails": null,
  "caseHistory": [
    {
      "reg": "135/2020",
      "causeListType": null,
      "judge": "District and Sessions Judge",
      "purpose": "Appearance",
      "nextHearingDate": "06-08-2020",
      "businessDate": "09-07-2020"
    },
    {
      "reg": "135/2020",
      "causeListType": null,
      "judge": "District and Sessions Judge",
      "purpose": "Appearance",
      "nextHearingDate": "18-08-2020",
      "businessDate": "06-08-2020"
    },
    {
      "reg": "135/2020",
      "causeListType": null,
      "judge": "District and Sessions Judge",
      "purpose": "Appearance",
      "nextHearingDate": "16-09-2020",
      "businessDate": "18-08-2020"
    }
  ],
  "orders": [
    {
      "number": "1",
      "orderDate": "09-07-2020",
      "judge": null,
      "attachment": null,
      "orderType": null,
      "orderId": "8acd04f57027fe8c8a318e95d0ca74a7",
      "downloadedAt": null
    },
    {
      "number": "2",
      "orderDate": "06-08-2020",
      "judge": null,
      "attachment": null,
      "orderType": null,
      "orderId": "af2538a37a645f61a09c177924d3ecb5",
      "downloadedAt": null
    },
    {
      "number": "3",
      "orderDate": "18-08-2020",
      "judge": null,
      "attachment": null,
      "orderType": null,
      "orderId": "6e96db2dfa0d699908f8d5fed84af3ae",
      "downloadedAt": null
    }
  ],
  "objections": null,
  "category": null,
  "subCategory": null,
  "subSubCategory": null,
  "fir": null,
  "earlierCourts": null,
  "documents": null,
  "linkedCases": null,
  "transfers": []
}

Download a 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

POSThttps://api.caseprimus.ai/api/caseprimus/v1/case-lookup/orders/download

Request headers

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

No API key yet? See Authentication.

Input parameters

FieldDescription
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

Request
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": "8acd04f57027fe8c8a318e95d0ca74a7"
  }'

Responses

200The order's document.
400Malformed input (60001), this search record does not exist (SEARCH_RECORD_NOT_FOUND, 60436), or this court's orders cannot be downloaded right now (COURT_TYPE_NOT_SUPPORTED_FOR_ORDERS, 60437).
403Caller lacks the case.write permission, or a free-trial account has used its order-download allowance (FREE_PLAN_USAGE_LIMIT_EXCEEDED, 61443).
404The orderId is not one of this case's orders (ORDER_NOT_FOUND, 60434).
422The court has no document for this order (ORDER_DOWNLOAD_FAILED, 60433; details.reason, null when no reason is known).
503Still being downloaded after 55 seconds (ORDER_DOWNLOAD_NOT_READY, 61469). Send the same request again (Retry-After; details.retryAfterSeconds).

Response fields (HTTP 200)

FieldDescription
orderId
string
url
string

Signed link, valid for 5 minutes. Never store it.

billed
boolean

Whether this download was charged for. False for an order you had already downloaded, which is served from store for free. True means one unit was counted - which only happens when a document was actually delivered, so a call that answers 422 or 503 costs nothing. Added; a response from before it is absent rather than false.

Response 200
{
  "orderId": "8acd04f57027fe8c8a318e95d0ca74a7",
  "url": "https://files.example.com/hrfb010051662020-9f8e7d6c5b4a.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=...",
  "billed": true
}

Download all orders of a case as a zip

Starts a job that puts every order document of one case into a single zip. Send the searchId from a previous case lookup. The call returns at once with a jobId; poll the matching GET endpoint for the status and, once it is COMPLETE, a signed link to the zip. Most courts only release a document inside a court session, so a case with many orders takes minutes rather than seconds. Billing is per order at the same rate as a single order download, and only for the orders you have not already downloaded - the ones you have are put in the zip at no extra charge. The response says how many of each before you wait. Requires case.write.

Request URL

POSThttps://api.caseprimus.ai/api/caseprimus/v1/case-lookup/orders/download-all

Request headers

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

No API key yet? See Authentication.

Input parameters

FieldDescription
searchId
string
Required

The searchId returned by the case lookup. Every order on that case goes into the zip.

Sample request

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

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

Responses

200The bundle job was accepted.
400Malformed input (60001), this search record does not exist (SEARCH_RECORD_NOT_FOUND, 60436), or the case has no order documents (EXPORT_NO_ORDERS, 61206).
403Caller lacks the case.write permission, or a free-trial account has used its order-download allowance (FREE_PLAN_USAGE_LIMIT_EXCEEDED, 61443).
500The bundle could not be queued (EXPORT_UNAVAILABLE, 61201). Nothing is charged; send the request again.

Response fields (HTTP 200)

FieldDescription
jobId
string

Poll this with GET /case-lookup/orders/download-all/{jobId} to get the zip.

status
enum

PENDING when the job is accepted. The zip is ready when the bundle reports COMPLETE.

PENDING
orders
object

What the zip will contain, and what this request is charged for.

total
integer

How many orders go into the zip.

billable
integer

How many are charged for - those not already downloaded.

alreadyAvailable
integer

How many were already downloaded. Included in the zip, not charged again.

Response 200
{
  "jobId": "CPEJ0bundledemo00001",
  "status": "PENDING",
  "orders": {
    "total": 12,
    "billable": 9,
    "alreadyAvailable": 3
  }
}

Get the zip of a case's orders

Reports on a bundle started with the download-all endpoint. While the zip is being produced the status is PENDING or PROCESSING. Once it is COMPLETE the response carries url, a signed link to the zip that is valid for an hour and generated fresh on every call, so do not store it. A bundle that could not be produced comes back FAILED with failureReason. Polling is free. Requires case.read.

Request URL

GEThttps://api.caseprimus.ai/api/caseprimus/v1/case-lookup/orders/download-all/{jobId}

Request headers

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

No API key yet? See Authentication.

Path parameters

NameInRequiredDescription
jobIdpathRequiredThe jobId returned when the bundle was started.

Sample request

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

curl "$BASE/case-lookup/orders/download-all/DOWNLOAD_ALL_ID" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"

Responses

200The bundle's status, and the zip once it is complete.
400Malformed jobId (60001), or no such bundle for this account (EXPORT_JOB_NOT_FOUND, 61200).
403Caller lacks the case.read permission.

Response fields (HTTP 200)

FieldDescription
_id
string
kind
enum
CASE_ORDERS_EXPORT
resourceLabel
string

The case the orders belong to.

created
integer (int64)
status
enum

PENDING or PROCESSING while the zip is being made, then COMPLETE or FAILED.

PENDINGPROCESSINGCOMPLETEFAILED
url
string or null

Signed link to the zip, valid for an hour. Only on COMPLETE. Never store it.

expiresIn
integer or null

Seconds the link stays valid. Only on COMPLETE.

failureReason
string or null

Why the bundle failed. Only on FAILED.

orders
object
total
integer
billable
integer
Response 200
{
  "_id": "CPEJ0bundledemo00001",
  "kind": "CASE_ORDERS_EXPORT",
  "resourceLabel": "HRFB010051662020",
  "created": 1760774400000,
  "status": "PROCESSING",
  "failureReason": null,
  "orders": {
    "total": 12,
    "billable": 9
  }
}

Summarise a looked-up case with AI

Generates an AI summary of a case you have looked up, with a risk level and the reasoning behind it, without adding the case to a watchlist. Send the searchId from the case lookup. CasePrimus reads the document of every order and summarizes the case. The call returns immediately with an _id; poll the summary endpoint for the result. A case with no orders completes immediately. Every call starts a new summary, so call it again to regenerate. The most recent summary is also returned as latestSummary on the case lookup. Requires case.write.

Request URL

POSThttps://api.caseprimus.ai/api/caseprimus/v1/case-lookup/summarize

Request headers

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

No API key yet? See Authentication.

Input parameters

FieldDescription
searchId
string
Required

The searchId returned by the case lookup.

Sample request

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

curl -X POST "$BASE/case-lookup/summarize" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searchId": "CPCSH0exampledemo0001"
  }'

Responses

200Summarization job queued (PENDING), or completed immediately (COMPLETE) for a case with no orders to read.
400Malformed input (60001), or the searchId is not one of this account's lookups (SEARCH_RECORD_NOT_FOUND, 60436).
403Caller lacks the case.write permission, or a free-trial account has used its summarization allowance (FREE_PLAN_USAGE_LIMIT_EXCEEDED, 61443).
500The summary request could not be started (CASE_LOOKUP_FAILED, 60406). Try again shortly.

Response fields (HTTP 200)

FieldDescription
_id
string

The id of the summary request. Use it to poll for the result.

status
enum

PENDING while the summary is being produced; COMPLETE straight away for a case with no orders. A FAILED status only ever appears when you poll.

PENDINGCOMPLETE
Response 200
{
  "_id": "CPCSS0exampledemo0001",
  "status": "PENDING"
}

Get an AI case summary

Returns the current status of a summary you requested. orderSummaries, riskLevel and caseSummary are included on every poll, not only once the status is COMPLETE, so you can show each order's summary as soon as it finishes. Poll until the status is COMPLETE or FAILED (error says why). An order's attachment is only "AVAILABLE" or null: the document itself comes from the order download endpoint. caseLabels says what the case is about, with the evidence it was read from in caseLabelBasis and caseLabelEvidence. Requires case.read.

Request URL

GEThttps://api.caseprimus.ai/api/caseprimus/v1/case-lookup/summarize/{id}

Request headers

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

No API key yet? See Authentication.

Path parameters

NameInRequiredDescription
idpathRequiredThe _id returned when you requested the summary.

Sample request

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

curl "$BASE/case-lookup/summarize/SUMMARIZE_ID" \
  -H "X-CasePrimus-Api-Key: $CASEPRIMUS_API_KEY"

Responses

200Current summarization status.
400This summary request does not exist (CASE_SUMMARY_NOT_FOUND, 60435), or the id is malformed (60001).
403Caller lacks the case.read permission.

Response fields (HTTP 200)

FieldDescription
_id
string

The id of the summary request.

status
enum
PENDINGCOMPLETEFAILED
riskLevel
enum or null

The risk level once the summary is complete: VERY_HIGH, HIGH, MODERATE, LOW or UNCLASSIFIED. Null until then.

VERY_HIGHHIGHMODERATELOWUNCLASSIFIED
caseSummary
string or null

The summary of the case. Null until it is complete.

riskJustification
string or null

Why this risk level was given. Null until the summary is complete.

caseLabels
array of string or null

What this case is ABOUT, from the same analysis call that wrote `caseSummary`. The same catalogue the watchlist and the litigation report use, so the three never disagree about what a case is. One or more ids, or `PROCEDURAL_ONLY` (neither the orders nor the court record reveal the subject matter) or `OTHERS` (the subject matter is clear but we have no id for it). Null until the analysis completes.

caseLabelBasis
enum or null

Which evidence the labels came from. `ORDER` - the case's own orders say so. `RECORD` - the case has no readable order and the label comes from the court's index entry, which is weaker and never reads HIGH. `BOTH` - they agree. `NEITHER` - `PROCEDURAL_ONLY`.

ORDERRECORDBOTHNEITHER
caseLabelConfidence
enum or null

How good the evidence is, not how strongly we feel. A label alleging conduct requires an order to describe that conduct, never a statute name.

HIGHMEDIUMLOW
caseLabelEvidence
string or null

The words that decided the labels, quoted. Published so a label can be checked rather than taken on trust.

casePartySide
enum or null

Which side the company is on. The same outcome words mean opposite things depending on it.

PETITIONERRESPONDENTBOTHUNCLEAR
caseSuggestedLabel
object or null

Set only where `caseLabels` is `OTHERS`: our own proposal for what this kind of case should be called, because a case we cannot categorise is still a case you need described.

id
string
label
string
why
string
orderSummaries
array of object

A summary for each order, each with its own status.

orderKey
string

The orderId of the order, as in the lookup's orders list.

orderNumber
string or null
orderDate
string or null
judge
string or null
orderType
string or null
attachment
enum or null

AVAILABLE when a document was found for the order, null when not. It is never a link: get the document with POST /case-lookup/orders/download.

AVAILABLE
status
enum

PENDING while being read; COMPLETE with a summary; SKIPPED when the order's document could not be read (error says why); FAILED when the document was read but the summary could not be produced.

PENDINGCOMPLETESKIPPEDFAILED
summary
string or null

Null until the order is COMPLETE.

detectedLanguage
string or null

The language of the order, when it is not English or was detected.

error
string or null

Why the order was SKIPPED or FAILED. Otherwise null.

errorClass
string or null

For a FAILED order, the kind of failure (for example TOKEN_LIMIT, TIMEOUT, RATE_LIMIT, SERVER_ERROR). Otherwise null.

computedAt
integer or null

Epoch ms when the order's status was settled. Null while PENDING.

error
string or null

Why the summary failed, if it did. Otherwise null.

Response 200
{
  "_id": "CPCSS0exampledemo0001",
  "status": "PENDING",
  "riskLevel": null,
  "caseSummary": null,
  "riskJustification": null,
  "caseLabels": null,
  "caseLabelBasis": null,
  "caseLabelConfidence": null,
  "caseLabelEvidence": null,
  "casePartySide": null,
  "caseSuggestedLabel": null,
  "orderSummaries": [
    {
      "orderKey": "8acd04f57027fe8c8a318e95d0ca74a7",
      "orderNumber": "1",
      "orderDate": "09-07-2020",
      "judge": null,
      "orderType": null,
      "attachment": "AVAILABLE",
      "status": "COMPLETE",
      "summary": "Adjourned the application to 06-08-2020 for appearance of the parties.",
      "detectedLanguage": "English",
      "error": null,
      "errorClass": null,
      "computedAt": 1757000071000
    },
    {
      "orderKey": "af2538a37a645f61a09c177924d3ecb5",
      "orderNumber": "2",
      "orderDate": "06-08-2020",
      "judge": null,
      "orderType": null,
      "attachment": "AVAILABLE",
      "status": "PENDING",
      "summary": null,
      "detectedLanguage": null,
      "error": null,
      "errorClass": null,
      "computedAt": null
    },
    {
      "orderKey": "6e96db2dfa0d699908f8d5fed84af3ae",
      "orderNumber": "3",
      "orderDate": "18-08-2020",
      "judge": null,
      "orderType": null,
      "attachment": "AVAILABLE",
      "status": "PENDING",
      "summary": null,
      "detectedLanguage": null,
      "error": null,
      "errorClass": null,
      "computedAt": null
    }
  ],
  "error": null
}

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.

CodeCourt or tribunal
SCSupreme Court of India
HCHigh Courts
DCDistrict Courts
CCConsumer Commissions
NCLTNational Company Law Tribunal
NCLATNational Company Law Appellate Tribunal
DRTDebts Recovery Tribunals
DRATDebts Recovery Appellate Tribunals
GSTATGoods and Services Tax Appellate Tribunal
CESTATCustoms, Excise and Service Tax Appellate Tribunal
NGTNational Green Tribunal
SATSecurities Appellate Tribunal
ITATIncome Tax Appellate Tribunal
APTELAppellate Tribunal for Electricity

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.

Summary statuses

StatusMeaning
PENDINGThe summary is still being produced. Order summaries that are finished are already included.
COMPLETEThe summary, risk level and risk justification are ready.
FAILEDThe summary could not be produced. The error field says why.

Risk levels

The riskLevel field of a summary uses these values.

ValueMeaning
VERY_HIGHVery high risk
HIGHHigh risk
MODERATEModerate risk
LOWLow risk
UNCLASSIFIEDNo risk level has been assigned

Decision support, not legal advice

Summaries and risk levels are produced by AI to help your team review a case faster. Have a qualified person confirm anything you rely on.

Errors

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

StatusCodeMessage
4004006Invalid/bad value provided for the CNR
40060435This case summary request does not exist
40060436This search record does not exist
40061200Export job does not exist
40061206This case has no order documents to download
40460434No matching order was found for the number and date provided
40460438No case was found at the court for this reference. Check the court, bench, case type, number and year, and try again
42260433Could not download this order right now, please try again shortly
50060406Could not look up this case right now, please try again shortly
50361469This 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 start monitoring the case?

No. A lookup is one-time and on demand. It starts no monitoring and needs no party. To follow a case, add it with the Case Monitoring API, or watch a company or person with the Parties Watchlist API.

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. To get every order, download them as one zip.

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, CESTAT, NGT, SAT, ITAT and APTEL tribunals.

What happens if the case does not exist?

If the court has no such case you get a 404 with the code CASE_NOT_FOUND_AT_COURT, and nothing is charged. If the reference matches more than one case you get a 400 with the code 4003; send a more specific identifier.

What does the AI summary return?

A plain-language case summary, a risk level, a written risk justification, and a summary for each order on the case. The request returns immediately with an _id, and the summary is ready when the status is COMPLETE.

Can I generate a summary again?

Yes. Every request starts a new summary. The most recent one is returned as latestSummary on the case lookup.

Is the risk level legal advice?

No. The summary and risk level are produced by AI as decision support. Have a qualified person confirm anything you rely on.