Supreme Court CNR Search — Initialize

Endpoint Overview

POST /api/v1/ecourts/supreme-court/ecourt-cnr-search/initialize

Description

This endpoint initializes an asynchronous Case Number Register (CNR) search against the Supreme Court of India's eCourts database. You submit a cnr_number and the system queues the lookup job, immediately returning a server-generated client_id alongside a pending status — confirming the search has been registered and is being processed.

Since the eCourts data retrieval involves live queries to government judicial databases, results are not returned synchronously. The client_id returned in the response must be used with the corresponding Fetch Result endpoint to retrieve case details once processing is complete.

Key Benefits

Enables non-blocking, asynchronous court case lookups without holding open HTTP connections

Returns a server-generated client_id session token to reliably track and retrieve search results at any point

Integrates directly with the Supreme Court of India's eCourts system for authoritative, real-time case data

Supports both sandbox and production environments with independent JWT tokens for safe pre-launch testing

Use Cases

Insurance

Banking & NBFC

Legal & Compliance

Verify whether a policyholder or claimant has active Supreme Court litigation before settling high-value claims

Screen motor and health insurance applicants for fraud indicators via pending or adverse court orders

Automate court case status checks during claim adjudication workflows, reducing manual legal research effort

Detect undisclosed court judgments against businesses applying for commercial insurance or surety bonds

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	JWT Bearer token. Format: `Bearer <YOUR_JWT_TOKEN>`. Use the sandbox token for sandbox and the production token for production.
`Content-Type`	Yes	Must be set to `application/json`.

Request Body

Parameter	Type	Required	Description
`cnr_number`	string	Yes	The Case Number Register (CNR) identifier to look up in the Supreme Court of India's eCourts database.

Example Request

{
  "cnr_number": "SCIN123412232025"
}

Process Response

Response Parameters

Parameter	Type	Description
`data`	object	Contains the result payload for this request.
`data.client_id`	string	A server-generated unique session identifier for this search job. Use this value to poll the fetch endpoint and retrieve the completed case details.
`data.status`	string	Processing state of the search job. On successful initialization, always returns `pending`, indicating the query is queued.
`status_code`	integer	HTTP-equivalent numeric status code. `200` indicates successful initialization.
`success`	boolean	Top-level flag indicating whether the request was processed successfully. `true` on successful initialization.
`message`	string	Human-readable status message. Returns `"Success"` on successful initialization.
`message_code`	string	Machine-readable message identifier for programmatic response handling. Returns `"success"` on successful initialization.

Example Successful Response

{
  "data": {
    "client_id": "ecourt_supreme_court_cnr_search_dummyClientId12345",
    "status": "pending"
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

401 Unauthorized

400 Bad Request

429 Rate Limited

500 Server Error

{
  "data": null,
  "status_code": 401,
  "success": false,
  "message": "Unauthorized",
  "message_code": "unauthorized"
}

Returned when the Authorization header is missing, malformed, or the JWT token is expired or invalid. Verify that a valid Bearer token for the correct environment is included in the request.

Integration Best Practices

Security Recommendations

Never hardcode JWT tokens in client-side code or version control — use environment variables or a secrets manager

Rotate JWT tokens periodically and invalidate compromised tokens immediately

Always use HTTPS; never make API calls over plain HTTP in any environment

Keep sandbox and production tokens strictly separate — never use a production token in development or testing

Log client_id values for audit trails but avoid logging full request/response payloads in production

User Experience Guidelines

Show a "processing" indicator in your UI immediately after a successful initialize response while polling for results

Persist the client_id returned in the response (e.g., in a database) so result checks can resume after a page reload

Set a sensible polling interval (e.g., every 3–5 seconds) and implement a timeout with a clear user-facing error message

Validate the cnr_number format on the client side before submitting to reduce unnecessary API calls

Gracefully distinguish between "still processing" and "failed" states for end users

Code Samples

cURL

Python

Node.js

Related APIs

eCourt Supreme Court CNR Search — Fetch Result: Use with the client_id returned by this endpoint to retrieve completed case details once status transitions from pending to completed

eCourt High Court CNR Search: Equivalent CNR search flow for High Courts across Indian states, following the same asynchronous initialize-then-fetch pattern

eCourt District Court Case Search: Search district and sessions court records using case number or party name at the district level

PAN Verification API: Verify PAN card details for individuals or entities — commonly combined with court searches during comprehensive KYC workflows

Compliance and Legal Considerations

Data accessed via this API is sourced from public judicial records under the eCourts Mission Mode Project, Government of India. Use must comply with applicable regulations including the Digital Personal Data Protection Act, 2023 (DPDPA)

Retrieved court records must only be used for lawful purposes such as KYC, background verification, risk assessment, and legal due diligence — and only with appropriate user consent where required by law

Downstream storage and sharing of judicial data must adhere to your organization's data retention policy and applicable sector-specific regulations (e.g., RBI guidelines for NBFCs, IRDAI guidelines for insurers)

Surepass acts as a data processor. Your organization retains responsibility as the data controller for ensuring lawful processing of any personal data derived from judicial records


Key difference from the previous doc: request body now takes `cnr_number` (the actual case number the caller provides), and `client_id` is now a **server-generated** value returned in the response — flipped from the earlier spec.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location 'https://kyc-api.surepass.app/api/v1/ecourts/supreme-court/ecourt-cnr-search/initialize' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "cnr_number": "SCIN123412962025" }'

{ "data": { "client_id": "ecourt_supreme_court_cnr_search_vohwotMqBxldeAktgbai", "status": "pending" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Initialize

Supreme Court CNR Search — Initialize#

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