eCourts Case Number - Search

Endpoint Overview

POST /api/v1/ecourts/case-number/search

Description

The eCourts Case Number - Search API is the primary case retrieval endpoint in the eCourts Case Number suite. It performs a detailed search for a specific court case using a combination of jurisdiction parameters (state, district, court complex) and case identifiers (case type, case number, year), returning an exhaustive record of the case including filing details, registration information, CNR number, case status, parties involved, applicable acts and sections, FIR details, complete hearing history, and all interim and final orders.

This endpoint is the culmination of the hierarchical lookup workflow: State → District → Court Complex → Case Type → Case Search. The preceding lookup APIs provide the exact input values required by this endpoint, ensuring that every request targets a valid and precise court jurisdiction. Once called, this API returns a rich, structured dataset that encapsulates the full lifecycle of a court case — from filing through hearings to final disposal — making it an indispensable tool for legal research, compliance verification, litigation tracking, and due diligence.

Key Benefits

Comprehensive Case Data: Returns the complete case record in a single API call — including filing details, registration, CNR number, case status, disposal nature, parties, advocates, applicable laws, FIR linkage, full hearing history, interim orders, final orders, and transfer details.

Structured & Machine-Readable: All data is returned in a well-organized JSON structure with dedicated nested objects for acts, FIR details, case history, and orders — enabling seamless programmatic consumption and storage.

End-to-End Case Lifecycle: Covers the full timeline of a case from first hearing date to decision date, with granular hearing-by-hearing history including judge name, purpose of hearing, and next date.

Unique Case Identification: Returns the CNR (Case Number Record) number — India's universal unique case identifier — enabling cross-referencing with other eCourts lookup methods and official court portals.

Use Cases

Legal & Law Firms

Banking & Financial Services

Insurance & Risk Management

HR & Background Verification

Case Monitoring & Tracking: Automate tracking of active litigation by periodically fetching case status, upcoming hearing dates, and new orders for matters being handled by the firm.

Litigation Research: Quickly retrieve full case records including applicable acts, sections, and disposal outcomes to support legal research and precedent analysis.

Client Reporting: Generate comprehensive case status reports for clients including hearing history, interim orders, and next date of hearing.

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token for authentication. Format: `Bearer <JWT_TOKEN>`. Use the appropriate token for the target environment (sandbox or production).
`Content-Type`	Yes	Must be set to `application/json`.

Request Body

Parameter	Type	Required	Description
`state_name`	String	Yes	The name of the state or union territory in snake_case format. Obtain valid values from the List States API (e.g., `delhi`, `maharashtra`, `uttar_pradesh`).
`district_name`	String	Yes	The name of the district within the specified state. Obtain valid values from the List Districts API (e.g., `Shahdara`, `Central`, `North`).
`court_complex_name`	String	Yes	The full name of the court complex within the specified district. Obtain valid values from the List Court Complex API (e.g., `Chief Metropolitan Magistrate, Shahdara, KKD`).
`case_type_name`	String	Yes	The case type code and description as returned by the List Case Types API (e.g., `CR Cases - CRIMINAL CASE`, `HMA - HINDU MARRIAGE ACT`).
`case_number`	String	Yes	The numeric case number to search for (e.g., `795`).
`year`	String	Yes	The four-digit year of the case (e.g., `2025`).

Example Request

{
  "state_name": "delhi",
  "district_name": "Shahdara",
  "court_complex_name": "Chief Metropolitan Magistrate, Shahdara, KKD",
  "case_type_name": "CR Cases - CRIMINAL CASE",
  "case_number": "795",
  "year": "2025"
}

Process Response

Response Parameters

Parameter	Type	Description
`data`	Object	The main response object containing all case details.
`data.client_id`	String	Unique Surepass transaction identifier for this API call.
`data.court_name`	String	Name of the court where the case is registered.
`data.state`	String	State of the court jurisdiction.
`data.district`	String	District of the court jurisdiction.
`data.case_type`	String	Case type code (e.g., `CR Cases`).
`data.court_complex`	String	Full name of the court complex.
`data.case_number`	String	The case number searched.
`data.year`	String	The year of the case.
`data.filing_number`	String	The filing number assigned to the case.
`data.filing_date`	String	Date the case was filed (format: `YYYY-MM-DD`).
`data.registration_number`	String	The registration number assigned upon case registration.
`data.registration_date`	String	Date the case was registered (format: `YYYY-MM-DD`).
`data.cnr_number`	String	The unique CNR (Case Number Record) identifier — India's universal case identifier.
`data.first_hearing_date`	String	Date of the first hearing (format: `YYYY-MM-DD`).
`data.decision_date`	String	Date the final decision was made (format: `YYYY-MM-DD`). Empty if case is pending.
`data.case_status`	String	Current status of the case (e.g., `Case disposed`, `Pending`).
`data.nature_of_disposal`	String	How the case was disposed (e.g., `SETTLED IN LOK ADALAT`). Empty if case is pending.
`data.court_number_and_judge`	String	Court number and the presiding judge's designation.
`data.petitioner`	String	Name of the petitioner/complainant.
`data.petitioner_advocate`	String	Name of the petitioner's advocate. May be empty.
`data.respondent`	String	Name of the respondent/accused.
`data.respondent_advocate`	String	Name of the respondent's advocate. May be empty.
`data.acts`	Array	List of acts and sections under which the case is filed.
`data.acts[].under_act`	String	Name of the act (e.g., `Narcotic Drugs and Psychotropic Substances Act 1985`).
`data.acts[].under_section`	String	Section number under the act (e.g., `27`).
`data.fir_details`	Object	FIR (First Information Report) details linked to the case.
`data.fir_details.fir_number`	String	FIR number.
`data.fir_details.police_station`	String	Name of the police station where the FIR was filed.
`data.fir_details.year`	String	Year the FIR was filed.
`data.case_history`	Array	Chronological list of all hearings conducted in the case.
`data.case_history[].judge`	String	Name/designation of the judge for that hearing.
`data.case_history[].business_on_date`	String	Date the hearing was conducted (format: `YYYY-MM-DD`).
`data.case_history[].hearing_date`	String	Next hearing date assigned (format: `YYYY-MM-DD`). Value `1800-01-01` indicates no next date (case disposed).
`data.case_history[].purpose_of_hearing`	String	Purpose of the hearing (e.g., `Misc./ Appearance`, `Disposed`).
`data.interim_orders`	Array	List of interim orders passed during the case proceedings.
`data.interim_orders[].order_number`	String	Serial number of the order.
`data.interim_orders[].order_date`	String	Date the order was passed (format: `YYYY-MM-DD`).
`data.interim_orders[].order_details`	String	Description or title of the order.
`data.final_orders`	Array	List of final orders/judgments. Empty array if no final orders have been passed.
`data.transfer_details`	Array	List of case transfer records if the case was transferred between courts. Empty array if no transfers occurred.
`status_code`	Integer	HTTP status code of the response (e.g., `200`).
`success`	Boolean	Indicates whether the API call was successful (`true` or `false`).
`message`	String	Human-readable response message (e.g., `Success`).
`message_code`	String	Machine-readable message code (e.g., `success`).

Example Successful Response

{
  "data": {
    "client_id": "ecourt_case_number_search_BOlfLHylllCbUuhrWZBu",
    "court_name": "Chief Metropolitan Magistrate, Shahdara, KKD",
    "state": "delhi",
    "district": "Shahdara",
    "case_type": "CR Cases",
    "court_complex": "Chief Metropolitan Magistrate, Shahdara, KKD",
    "case_number": "795",
    "year": "2025",
    "filing_number": "2471/2025",
    "filing_date": "2025-02-18",
    "registration_number": "795/2025",
    "registration_date": "2025-02-18",
    "cnr_number": "DLSH020024712025",
    "first_hearing_date": "2025-02-18",
    "decision_date": "2025-03-10",
    "case_status": "Case disposed",
    "nature_of_disposal": "SETTLED IN LOK ADALAT",
    "court_number_and_judge": "455-Chief Judicial Magistrate",
    "petitioner": "STATE",
    "petitioner_advocate": "",
    "respondent": "SHAMBHU MISR",
    "respondent_advocate": "",
    "acts": [
      {
        "under_act": "Narcotic Drugs and Psychotropic Substances Act 1985",
        "under_section": "27"
      }
    ],
    "fir_details": {
      "fir_number": "487",
      "police_station": "Shahdara",
      "year": "2024"
    },
    "case_history": [
      {
        "judge": "Chief Judicial Magistrate",
        "business_on_date": "2025-02-18",
        "hearing_date": "2025-03-08",
        "purpose_of_hearing": "Misc./ Appearance"
      },
      {
        "judge": "Chief Judicial Magistrate",
        "business_on_date": "2025-03-08",
        "hearing_date": "2025-03-10",
        "purpose_of_hearing": "Misc./ Appearance"
      },
      {
        "judge": "Chief Judicial Magistrate",
        "business_on_date": "2025-03-10",
        "hearing_date": "1800-01-01",
        "purpose_of_hearing": "Disposed"
      }
    ],
    "interim_orders": [
      {
        "order_number": "1",
        "order_date": "2025-02-18",
        "order_details": "COPY OF ORDER"
      }
    ],
    "final_orders": [],
    "transfer_details": []
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Authentication Error (401)

Invalid Parameters (422)

Invalid State Name (400)

Invalid District Name (400)

Invalid Court Complex Name (400)

Internal Server Error (500)

{
    "data": null,
    "error": null,
    "message": "Your token is invalid. Please ensure that correct token is being used.",
    "status_code": 401,
    "success": false,
    "message_code": "invalid_token"
}

This error occurs when the JWT Bearer token is missing, invalid, malformed, or expired. Verify that you are passing a valid token in the Authorization header and that it corresponds to the correct environment (sandbox or production).

Integration Best Practices

Security Recommendations

Secure Token Storage: Never hardcode JWT tokens in source code or client-side applications. Store tokens securely using environment variables, secret managers (e.g., AWS Secrets Manager, HashiCorp Vault), or encrypted configuration files.

Token Rotation: Implement automatic JWT token refresh mechanisms to avoid service disruptions due to token expiry. Monitor token validity proactively.

HTTPS Only: Always communicate with the API over HTTPS. Never send requests over unencrypted HTTP connections.

Sensitive Data Handling: The response contains personally identifiable information (PII) such as names of petitioners, respondents, and FIR details. Encrypt this data at rest and in transit, and enforce role-based access controls within your application.

Audit Logging: Log all API calls (excluding sensitive response data) with timestamps and client_id for audit trail and troubleshooting purposes.

User Experience Guidelines

Cascading Selection Flow: Build a guided, step-by-step UI that walks users through State → District → Court Complex → Case Type → Case Number/Year. Populate each dropdown dynamically using the corresponding lookup API to prevent invalid inputs.

Loading States & Feedback: Display loading indicators while the API is processing the search, as court data retrieval may take a few seconds. Provide clear success/error messages to the user.

Rich Case Display: Present the response data in a well-structured layout — use separate sections for case overview (status, filing, registration), parties & advocates, acts & sections, FIR details, hearing timeline, and orders for easy scanning.

Hearing Timeline Visualization: Render the case_history array as a visual timeline or table, highlighting the most recent hearing and the next scheduled date. Flag hearing_date values of 1800-01-01 as "No further hearings (Disposed)".

Order Downloads: Where order_details indicates downloadable content (e.g., "COPY OF ORDER"), provide clear action buttons for users to access the order documents.

Code Samples

cURL

Python

Node.js

Java

Related APIs

eCourts Case Number - List States (GET /api/v1/ecourts/case-number/list-state): Retrieves the list of all available states and union territories. Use this as the first step to obtain valid state_name values.

eCourts Case Number - List Districts (GET /api/v1/ecourts/case-number/list-districts): Retrieves all districts within a given state. Use this as the second step to obtain valid district_name values.

eCourts Case Number - List Court Complex (GET /api/v1/ecourts/case-number/list-court-complex): Retrieves all court complexes within a given district and state. Use this as the third step to obtain valid court_complex_name values.

eCourts Case Number - List Case Types (GET /api/v1/ecourts/case-number/list-case-types): Retrieves all case types available in a given court complex. Use this as the fourth step to obtain valid case_type_name values.

eCourts CNR Search (POST /api/v1/ecourts/cnr/search): Search for a case directly using the CNR number if you already have it, bypassing the hierarchical lookup workflow.

Compliance and Legal Considerations

Public Court Records: The data returned by this API is sourced from the eCourts platform, which contains publicly available court records of Indian district and subordinate courts. However, usage must comply with applicable laws and the terms of service of the eCourts platform.

Data Privacy & PII: The response includes personally identifiable information (PII) such as names of petitioners, respondents, advocates, and FIR details. Organizations must handle this data in accordance with the Digital Personal Data Protection Act, 2023 (DPDPA) and any other applicable privacy regulations. Implement proper data minimization, access controls, and retention policies.

No Legal Advice: The data provided by this API is for informational and verification purposes only. It does not constitute legal advice, and the accuracy of records is dependent on the eCourts platform's data. Always verify critical case information through official court records.

Fair Usage & Rate Limiting: Adhere to Surepass's fair usage policy and API rate limits. Excessive automated scraping or bulk extraction of court data may violate terms of service.

Purpose Limitation: Use the case data only for legitimate business purposes such as KYC, due diligence, compliance verification, litigation tracking, or background checks. Do not use the data for harassment, discrimination, or any unlawful purpose.

Audit Trail: Maintain an audit trail of all case searches performed through this API, including timestamps, requesting user, and business justification, to demonstrate compliance during regulatory audits.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Case Number Search

eCourts Case Number - Search#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses