eCourts Case Number - List Court Complex

Endpoint Overview

GET /api/v1/ecourts/case-number/list-court-complex

Description

The eCourts Case Number - List Court Complex API retrieves a comprehensive list of all court complexes available within a specified district and state in the eCourts ecosystem. This endpoint represents the third and crucial step in the hierarchical jurisdiction lookup workflow: State → District → Court Complex → Case Search.

After identifying the target state (via the List States API) and the relevant district (via the List Districts API), developers must use this endpoint to fetch the specific court complexes where cases are heard. Indian judicial districts typically contain multiple court complexes — including District & Sessions Courts, Metropolitan Magistrate Courts, Family Courts, Juvenile Justice Boards, and specialized tribunals. Each court complex handles different types of cases and jurisdictions.

This API returns the full official names of court complexes in a human-readable string format, enabling you to build precise, cascading selection interfaces that guide users to the exact court complex before initiating a case number search.

Key Benefits

Granular Court Identification: Pinpoint the exact court complex within a district, eliminating ambiguity in case searches across multiple judicial establishments.

Dynamic & Up-to-Date Data: Fetches the latest court complex listings directly from the eCourts infrastructure, ensuring your application always reflects the current judicial setup.

Streamlined Workflow Integration: Seamlessly fits into the State → District → Court Complex → Case Search pipeline, enabling fully automated and guided case lookup experiences.

Comprehensive Court Coverage: Returns all types of court complexes including District Courts, Magistrate Courts, Family Courts, and Juvenile Justice Boards within a given district.

Use Cases

Legal Technology

Financial Services & Lending

Background Verification & Compliance

Case Management Platforms: Allow lawyers and litigants to select the precise court complex when looking up a case by number, ensuring accurate case retrieval from the correct judicial establishment.

Legal Research Tools: Enable legal researchers and paralegals to narrow down court complex jurisdictions before extracting case records for analysis, precedent research, or litigation tracking.

E-Filing Assistants: Pre-populate court complex dropdowns in e-filing workflows so that advocates can identify the correct filing destination within a district.

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 for authentication. Format: `Bearer <your_jwt_token>`
`Content-Type`	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
`state_name`	string	Yes	The Indian state or union territory in snake_case format (e.g., `"delhi"`, `"andhra_pradesh"`, `"tamil_nadu"`). This value should be obtained from the List States API.
`district_name`	string	Yes	The name of the district within the specified state (e.g., `"Shahdara"`, `"Central"`, `"East"`). This value should be obtained from the List Districts API.

Example Request

{
  "state_name": "delhi",
  "district_name": "Shahdara"
}

Process Response

Response Parameters

Parameter	Type	Description
`data`	array of strings	A list of court complex names available within the specified state and district. Each entry is the full official name of a court complex (e.g., `"District and Sessions Judge, Shahdara, KKD"`).
`status_code`	integer	HTTP status code of the response. `200` indicates a successful request.
`message_code`	string	A machine-readable code representing the result status (e.g., `"success"`).
`message`	string	A human-readable message describing the result of the API call (e.g., `"Success"`).
`success`	boolean	Indicates whether the API request was processed successfully. `true` for success, `false` for failure.

Example Successful Response

{
  "data": [
    "District and Sessions Judge, Shahdara, KKD",
    "Chief Metropolitan Magistrate, Shahdara, KKD",
    "Senior Civil Judge cum RC, Shahdara, KKD",
    "Principal Judge Family Court, Shahdara , KKD",
    "Juvenile Justice Board-VI, Shahdara, KKD"
  ],
  "status_code": 200,
  "message_code": "success",
  "message": "Success",
  "success": true
}

Possible Error Responses

Authentication Error (401)

Invalid State Name (400)

Invalid District 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 Authorization header is missing, the JWT token is invalid, malformed, or has expired. Generate a new JWT token and retry the request.

Integration Best Practices

Security Recommendations

Protect JWT Tokens: Store JWT tokens securely on the server side. Never expose tokens in client-side code, browser local storage, or version control repositories.

Use HTTPS Exclusively: Always communicate with the API over HTTPS to ensure data integrity and prevent man-in-the-middle attacks.

Rotate Tokens Regularly: Implement token refresh logic to replace expired tokens automatically. Do not use long-lived tokens in production environments.

Restrict API Key Access: Limit API key permissions and usage to only the required endpoints. Apply IP whitelisting where possible to reduce the attack surface.

User Experience Guidelines

Build Cascading Dropdowns: Implement a progressive State → District → Court Complex selection flow. Only fetch court complexes after the user has selected both a state and a district, keeping the interface responsive and relevant.

Cache Court Complex Lists: Court complexes within a district change infrequently. Cache the results locally (with a reasonable TTL of 24–48 hours) to reduce redundant API calls and improve UI responsiveness.

Display Friendly Labels: Present the full court complex names as returned by the API (e.g., "District and Sessions Judge, Shahdara, KKD") directly in the UI — they are already in a user-friendly format.

Handle Empty Results Gracefully: In rare cases, a district may return an empty court complex list. Display an appropriate message such as "No court complexes found for the selected district" rather than leaving the UI blank.

Code Samples

cURL

Python

Node.js

Related APIs

eCourts Case Number - List States (GET /api/v1/ecourts/case-number/list-state): Retrieves the list of all supported Indian states and union territories. Use this API as the first step to obtain valid state_name values required by the List Districts and List Court Complex APIs.

eCourts Case Number - List Districts (GET /api/v1/ecourts/case-number/list-districts): Retrieves the list of districts within a specified state. Use this API as the second step to obtain valid district_name values required by this List Court Complex API.

eCourts Case Number - Search (POST /api/v1/ecourts/case-number/search): Performs the actual case search by case number within a specified court complex. Use the court complex name returned by this API as an input parameter.

Compliance and Legal Considerations

Public Court Records: The data returned by this API pertains to publicly available court infrastructure information (court complex names and locations). It does not expose any personal or case-specific data.

Data Usage Policy: While court complex listings are public information, ensure that any downstream case search data retrieved using these court complexes is handled in compliance with applicable data protection regulations, including the Digital Personal Data Protection Act (DPDPA), 2023.

Fair Use & Rate Limiting: Adhere to Surepass's rate limiting policies and terms of service. Avoid excessive or abusive polling of this endpoint. Implement caching to minimize redundant requests.

Judicial Data Sensitivity: When using court complex data to build litigation screening or background verification workflows, ensure your processes comply with relevant labor laws, anti-discrimination regulations, and organizational policies governing the use of court records in decision-making.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location --request GET 'https://kyc-api.surepass.app/api/v1/ecourts/case-number/list-court-complex' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "state_name": "delhi", "district_name": "Shahdara" }'

{ "data": [ "District and Sessions Judge, Shahdara, KKD", "Chief Metropolitan Magistrate, Shahdara, KKD", "Senior Civil Judge cum RC, Shahdara, KKD", "Principal Judge Family Court, Shahdara , KKD", "Juvenile Justice Board-VI, Shahdara, KKD" ], "status_code": 200, "message_code": "success", "message": "Success", "success": true }

Get Court Complex List

eCourts Case Number - List Court Complex#

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