Ecourts CNR Search Advance

Endpoint Overview

POST /api/v1/ecourts/ecourt-cnr-search-adv

Description

The ECourt CNR Search Advanced API enables real-time retrieval of comprehensive case information from Indian eCourt systems using a Case Number Record (CNR). It supports both District Courts and High Courts, returning a rich dataset that includes case details, current status, party information, hearing history, interim orders, final judgements, and process/notice records — all in a single API call.

This API is built on top of the National Judicial Data Grid (NJDG) infrastructure and is ideal for legal-tech platforms, financial institutions, background verification providers, and compliance teams that need programmatic access to court records without manual portal lookups.

Key Benefits

Comprehensive Case Data: Retrieves case details, hearing history, orders, judgements, party names, advocates, and process records in one unified response.

Dual Court Support: Works seamlessly across both District Courts and High Courts using a single endpoint with a simple parameter switch.

Document Access: Provides pre-signed S3 URLs for interim orders and final judgements, enabling direct document download.

Automation-Ready: Eliminates the need for manual eCourts portal searches, enabling automated legal due diligence and case monitoring workflows.

Use Cases

Legal & Compliance

Financial Services

Background Verification

Law firms tracking the hearing schedules and case progression of their clients' matters across district and high courts.

Corporate legal teams monitoring ongoing litigation involving the company as petitioner or respondent.

Compliance departments verifying the litigation history of vendors, partners, or counterparties before onboarding.

Legal analytics platforms aggregating judgment data for trend analysis and reporting.

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer Token. Follow these steps to authenticate:

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

Generate JWT Token: Use your API key to generate a JWT token through Surepass's token issuance process.

Include in Requests: Add the token to the Authorization header as Bearer <YOUR_JWT_TOKEN>.

Different base URLs are used for sandbox and production environments:

Environment	Base URL
Sandbox	`https://sandbox.surepass.app`
Production	`https://kyc-api.surepass.app`

Note: Use the JWT token issued for the respective environment. Sandbox tokens will not work against the Production base URL and vice versa.

Request Parameters

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token in the format `Bearer <JWT_TOKEN>`
`Content-Type`	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
`cnr_number`	String	Yes	The Case Number Record (CNR) — a unique 16-character alphanumeric identifier assigned to each case in the eCourts system (e.g., `ABAS020001082020`).
`court_type`	String	Yes	Specifies the court type to search. Accepted values: `district_court` or `high_court`.

Example Request

{
    "cnr_number": "ABAS020001082020",
    "court_type": "district_court"
}

Process Response

Response Parameters

Top-Level Fields

Parameter	Type	Description
`status_code`	Integer	HTTP status code of the response (e.g., `200` for success).
`success`	Boolean	Indicates whether the request was successful (`true` / `false`).
`message`	String	A human-readable status message (e.g., `"Success"`).
`message_code`	String	A machine-readable status code (e.g., `"success"`).
`data`	Object	Root object containing the fetched case data.

`data` Object

Parameter	Type	Description
`client_id`	String	A unique identifier for this specific API request, used for tracking and audit purposes.
`cnr_number`	String	The CNR number that was queried.
`cnr_details`	Object	Nested object containing all case-related information.

`cnr_details.case_details`

Parameter	Type	Description
`case_type`	String	The type/category of the case (e.g., `CRA` for Criminal Appeal).
`filing_number`	String	The case filing number assigned at the time of filing.
`filing_date`	String (Date)	Date on which the case was filed (format: `YYYY-MM-DD`).
`registration_number`	String	The official registration number assigned after court admission.
`registration_date`	String (Date)	Date on which the case was registered (format: `YYYY-MM-DD`).

`cnr_details.case_status`

Parameter	Type	Description
`first_hearing_date`	String (Date)	Date of the first hearing scheduled for this case.
`next_hearing_date`	String (Date)	Date of the next scheduled hearing.
`case_stage`	String	Current procedural stage of the case (e.g., `"Notice And Record"`).
`court_number_and_judge`	String	The court number and the presiding judge's designation.
`decision_date`	String (Date)	Date on which the final decision/order was passed, if applicable.
`nature_of_disposal`	String	Indicates how the case was disposed (e.g., `"ACQUITTED"`).

`cnr_details.petitioner_and_advocate_details`

Parameter	Type	Description
`petitioner`	String	Full name of the petitioner/appellant in the case.
`advocate`	String	Full name of the advocate representing the petitioner.

`cnr_details.respondent_and_advocate_details`

Parameter	Type	Description
(Array of Strings)	Array	List of respondent names in the case.

`cnr_details.act_details` (Array)

Parameter	Type	Description
`under_act`	String	The act under which the case has been filed (e.g., `"Cr. P.C."`).
`under_section`	String	The specific section of the act invoked (e.g., `"374"`).

`cnr_details.subordinate_court_information_details`

Parameter	Type	Description
`case_number_and_year`	String	Case number and year from the subordinate/lower court.
`case_decision_date`	String	Date and nature of the decision in the subordinate court.

`cnr_details.case_history_details` (Array)

Parameter	Type	Description
`judge`	String	Name/designation of the judge presiding over the hearing.
`business_on_date`	String (Date)	Date on which the case was taken up for hearing.
`hearing_date`	String (Date) / null	Next hearing date as scheduled on that day; `null` if the case was disposed.
`purpose_of_hearing`	String	The stated purpose or agenda of the hearing (e.g., `"Notice And Record"`, `"Disposed"`).

`cnr_details.interim_orders_details` (Array)

Parameter	Type	Description
`order_number`	String	Sequential order number within the case.
`order_date`	String (Date)	Date on which the interim order was passed.
`order_details`	String	Description or type of the order (e.g., `"Copy of Order/Copy Final Order"`).
`status`	String	Status of the order document retrieval (e.g., `"success"`).
`order_details_url`	String (URL)	Pre-signed S3 URL to download the order PDF document. URLs are time-limited (expires in 600 seconds).

`cnr_details.final_orders_and_judgements_details` (Array)

Parameter	Type	Description
`order_number`	String	Sequential order number within the case.
`order_date`	String (Date)	Date on which the final order/judgment was passed.
`order_details`	String	Description or type of the final order.
`status`	String	Status of the document retrieval (e.g., `"success"`).
`order_details_url`	String (URL)	Pre-signed S3 URL to download the final order/judgment PDF. URLs are time-limited (expires in 600 seconds).

`cnr_details.case_transfer_and_establishment_details` (Array)

Parameter	Type	Description
(Empty Array)	Array	Contains transfer history if the case has been transferred between courts or establishments. Returns an empty array if no transfers have occurred.

`cnr_details.process_details` (Array)

Parameter	Type	Description
`process_id`	String	Unique identifier for the process/notice record.
`process_data`	String (Date)	Date on which the process/notice was issued.
`process_title`	String	Description of the process or notice issued (e.g., `"Notice to Respondent in Criminal Appeal."`).

Example Successful Response

{
    "data": {
        "client_id": "ecourt_cnr_search_adv_fxKlRurqzyZuQwFtYvBr",
        "cnr_number": "ABAS020001082020",
        "cnr_details": {
            "case_details": {
                "case_type": "CRA",
                "filing_number": "1928/2025",
                "filing_date": "2025-01-01",
                "registration_number": "339/2025",
                "registration_date": "2025-02-15"
            },
            "case_status": {
                "first_hearing_date": "2025-02-15",
                "next_hearing_date": "2025-03-08",
                "case_stage": "Notice And Record",
                "court_number_and_judge": "24-Additional District Judge",
                "decision_date": "2025-03-08",
                "nature_of_disposal": "ACQUITTED"
            },
            "petitioner_and_advocate_details": {
                "petitioner": "RAMESH AGGARWAL",
                "advocate": "Rajiv Talwar"
            },
            "respondent_and_advocate_details": [
                "INCOME TAX OFFICER",
                "STATE OF UNION TERRITORY",
                "MAX PACIFIC CORPORATION ITD",
                "SURESH AGGARWAL",
                "KARUN AGGARWAL"
            ],
            "act_details": [
                {
                    "under_act": "Cr. P.C.",
                    "under_section": "374"
                }
            ],
            "subordinate_court_information_details": {
                "case_number_and_year": "0003652 -  2025",
                "case_decision_date": "2025-01-01COMP"
            },
            "case_history_details": [
                {
                    "judge": "Additional District Judge",
                    "business_on_date": "2025-02-15",
                    "hearing_date": "2025-03-05",
                    "purpose_of_hearing": "Notice And Record"
                },
                {
                    "judge": "Additional District Judge",
                    "business_on_date": "2025-03-05",
                    "hearing_date": "2025-03-08",
                    "purpose_of_hearing": "Notice And Record"
                },
                {
                    "judge": "Additional District Judge",
                    "business_on_date": "2025-03-08",
                    "hearing_date": null,
                    "purpose_of_hearing": "Disposed"
                }
            ],
            "interim_orders_details": [
                {
                    "order_number": "1",
                    "order_date": "2025-02-15",
                    "order_details": "Copy of Order/Copy Final Order",
                    "status": "success",
                    "order_details_url": "https://aadhaar-kyc-docs.s3.amazonaws.com/ecourt_cnr_search_adv/ecourt_cnr_search_adv_fxKlRurqzyZuQwFtYvBr/district_court/CHCH010050522023/1_2025_02der-2026-05-01-122607177307.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=a8cca6b9c86ccfaa86859a8bd4e1c46e1fb1a11ba4fd64bad"
                },
                {
                    "order_number": "2",
                    "order_date": "2025-03-05",
                    "order_details": "Copy of Order/Copy Final Order",
                    "status": "success",
                    "order_details_url": "https://aadhaar-kyc-docs.s3.amazonaws.com/ecourt_cnr_search_adv/ecourt_cnr_search_adv_f7afc2c3e7625ed9b721532aa5294f21b6ee89eaaedf8a37b7"
                }
            ],
            "final_orders_and_judgements_details": [
                {
                    "order_number": "3",
                    "order_date": "2025-03-08",
                    "order_details": "Copy of Order/Copy Final Order",
                    "status": "success",
                    "order_details_url": "https://aadhaar-kyc-docs.s3.amazonaws.com/ecourt_cnr_search_adv/ecourt_cnr_search_adv_fxKlRurqzyZuQwFtYvBr/district_court/CHCH010050522023/9_2025_0363e78a5e325e3d6d1308f375e14e0efaf6396986c4933eb50a551"
                }
            ],
            "case_transfer_and_establishment_details": [],
            "process_details": [
                {
                    "process_id": "PCHCH010050522025_1_1",
                    "process_data": "2025-01-01",
                    "process_title": "Notice to Respondent in Criminal Appeal."
                },
                {
                    "process_id": "PCHCH010050522025_2_15",
                    "process_data": "2025-02-15",
                    "process_title": "Notice to Respondent in Criminal Appeal."
                },
                {
                    "process_id": "PCHCH010050522025_3_8",
                    "process_data": "2025-03-08",
                    "process_title": "Docket Calling Record of Decided Cases."
                }
            ]
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Unauthorized (401)

Invalid CNR (400)

Server Error (500)

{
    "status_code": 401,
    "success": false,
    "message": "Unauthorized. Invalid or missing Bearer token.",
    "message_code": "unauthorized"
}

Returned when the JWT Bearer token is absent, malformed, expired, or issued for a different environment (e.g., using a sandbox token against the production URL).

Integration Best Practices

Security Recommendations

Protect JWT Tokens: Never expose your JWT Bearer token in client-side code, public repositories, or logs. Store tokens in environment variables or a secrets manager.

Use Environment-Specific Tokens: Always use sandbox tokens for development and testing against https://sandbox.surepass.app, and only switch to production tokens (https://kyc-api.surepass.app) for live deployments.

Token Rotation: Rotate your JWT tokens periodically and immediately upon suspected compromise.

Pre-signed URL Handling: The order_details_url values in interim and final order responses are time-limited pre-signed S3 URLs that expire in 600 seconds. Download documents promptly and store them securely rather than relying on the URL for repeated access.

HTTPS Only: Always make API calls over HTTPS. Never transmit CNR numbers or Bearer tokens over unencrypted connections.

User Experience Guidelines

Validate CNR Format Early: Perform client-side validation of the cnr_number format (16-character alphanumeric) and court_type values before making an API call to reduce unnecessary round-trips.

Handle Null Hearing Dates Gracefully: The hearing_date field in case_history_details can be null when a case is disposed. Ensure your UI handles this gracefully (e.g., display "Disposed" instead of a blank date).

Display Order Documents Inline: Use the pre-signed order_details_url to provide an inline PDF viewer or a direct download button for orders. Avoid exposing the raw URL directly to end users.

Indicate Case Stage Clearly: Surface the case_stage and nature_of_disposal prominently in your UI so users can quickly assess whether a case is active or concluded.

Implement Retry Logic: For transient failures (5xx errors), implement exponential backoff with a maximum of 3 retries before surfacing an error to the user.

Log client_id for Support: Always log the client_id from each API response alongside your internal request identifiers to facilitate faster resolution when contacting Surepass support.

Code Samples

cURL

Python

Node.js

Related APIs

eCourt Case Status Search — Retrieve case status using party name, filing number, or advocate name without requiring a CNR number.

eCourt High Court Search — Dedicated endpoint for searching cases exclusively within High Court databases using case-specific parameters.

Court Record Verification — Verify the authenticity and current standing of a court case for KYC and due diligence workflows.

Criminal Court Check — Perform broad criminal litigation screening on individuals or entities across multiple courts in a single query.

Compliance and Legal Considerations

Data Privacy: Court case data fetched via this API is sourced from publicly available eCourts portals. However, storing, processing, or sharing personally identifiable information (PII) from case records — such as party names and advocate details — may be subject to applicable data protection regulations including the Digital Personal Data Protection Act, 2023 (DPDPA) in India. Ensure that your usage complies with all applicable laws and your organization's data handling policies.

Purpose Limitation: This API should be used solely for lawful purposes such as legal due diligence, KYC verification, background checks, or case management. Unauthorized use of court data for surveillance, harassment, or any purpose contrary to applicable law is strictly prohibited.

Data Accuracy: Case information is retrieved in near real-time from the eCourts system. While every effort is made to ensure accuracy, Surepass does not guarantee the completeness or currency of case data. Always cross-verify critical legal information directly with the concerned court.

Document Retention: Pre-signed S3 URLs for order documents expire within 600 seconds. If your application requires long-term access to case documents, download and securely store the PDFs in compliance with your document retention policy.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Top-Level Fields#

data Object#

cnr_details.case_details#

cnr_details.case_status#

cnr_details.petitioner_and_advocate_details#

cnr_details.respondent_and_advocate_details#

cnr_details.act_details (Array)#

cnr_details.subordinate_court_information_details#

cnr_details.case_history_details (Array)#

cnr_details.interim_orders_details (Array)#

cnr_details.final_orders_and_judgements_details (Array)#

cnr_details.case_transfer_and_establishment_details (Array)#

cnr_details.process_details (Array)#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses