eCourts Case Number - List Districts

Endpoint Overview

GET /api/v1/ecourts/case-number/list-districts

Description

The eCourts Case Number - List Districts API retrieves a comprehensive list of all districts available within a specified Indian state or union territory in the eCourts ecosystem. This endpoint is a critical step in the hierarchical lookup workflow for eCourts case search — after identifying the target state using the List States API, developers must use this endpoint to fetch the relevant district codes before performing a case-number-based search.

Each state or union territory in India is subdivided into judicial districts, and court cases are filed and managed at the district level. This API returns the list of supported district names for the given state in a human-readable format, enabling you to build dynamic, cascading dropdowns or selection interfaces that guide users from state → district → court → case lookup.

Key Benefits

Accurate Jurisdiction Mapping: Returns the precise list of judicial districts for any given state, ensuring users select the correct jurisdiction for case searches.

Dynamic UI Construction: Enables developers to build cascading, state-dependent district selection interfaces without hardcoding district data.

Comprehensive Coverage: Covers all judicial districts across all 36 states and union territories of India as maintained by the eCourts platform.

Standardized Data: Provides consistent, up-to-date district names aligned with the official eCourts database, eliminating discrepancies in manual data entry.

Use Cases

Legal Technology

Financial Services

Compliance & Background Verification

Case Management Platforms: Legal tech applications can use this API to dynamically populate district dropdowns when lawyers or paralegals search for court cases by case number, ensuring jurisdiction accuracy.

Litigation Tracking Systems: Automatically map case records to the correct district for portfolio-level court case monitoring across multiple states.

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 API authentication. Format: `Bearer <JWT_TOKEN>`. Use the appropriate token for your environment (sandbox or production).
`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 for which to retrieve the list of districts. This value must be one of the codes returned by the List States API (e.g., `"delhi"`, `"maharashtra"`, `"uttar_pradesh"`).

Example Request

{
  "state_name": "delhi"
}

Process Response

Response Parameters

Parameter	Type	Description
`data`	array of strings	A list of district names available within the specified state. Each entry is a human-readable district name (e.g., `"Central"`, `"North West"`).
`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 call was successful. `true` for success, `false` for failure.

Example Successful Response

{
  "data": [
    "Central",
    "East",
    "New Delhi",
    "North",
    "North East",
    "North West",
    "Shahdara",
    "South",
    "South East",
    "South West",
    "West"
  ],
  "status_code": 200,
  "message_code": "success",
  "message": "Success",
  "success": true
}

Possible Error Responses

Authentication Error (401)

Invalid State 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 your JWT tokens securely using environment variables or a secrets manager. Never hardcode tokens in source code or expose them in client-side applications.

Use HTTPS Only: Always communicate with the API over HTTPS to ensure data is encrypted in transit. Both sandbox and production base URLs enforce TLS.

Rotate Tokens Regularly: Implement a token refresh mechanism to minimize the risk window if a token is compromised.

Restrict API Key Access: Apply the principle of least privilege — limit API key permissions and whitelist IP addresses where possible.

User Experience Guidelines

Build Cascading Dropdowns: Use this API in combination with the List States API to create a seamless state → district selection flow. Fetch districts dynamically only after the user selects a state to keep the interface responsive and relevant.

Cache District Lists: District data changes infrequently. Cache the response for each state locally (e.g., for 24 hours) to reduce redundant API calls and improve UI responsiveness.

Provide Search/Filter: For states with many districts, implement a search or filter capability within the district dropdown to help users find their target district quickly.

Show Loading Indicators: Display a spinner or loading state while the district list is being fetched after a state selection to provide clear feedback to the user.

Code Samples

cURL

Python

Node.js

Related APIs

eCourts Case Number - List States: Retrieves the list of all Indian states and union territories supported by the eCourts system. Use this API first to obtain a valid state_name value required by the List Districts endpoint.

eCourts Case Number - List Courts: Retrieves the list of courts available within a specific district. Use this after obtaining the district name from the List Districts API.

eCourts Case Number - Search: Performs the actual case lookup using a case number, state, district, and court. This is the final step in the eCourts case search workflow.

Compliance and Legal Considerations

Public Data Access: The data returned by this API is sourced from the eCourts platform, which is a public government initiative. However, developers should ensure that the downstream use of court case data complies with applicable Indian laws and regulations, including the Information Technology Act, 2000 and relevant High Court / Supreme Court guidelines on access to judicial data.

Data Privacy: While state and district names are non-sensitive, any subsequent case data retrieved using these identifiers may contain personally identifiable information (PII). Ensure your application handles such data in compliance with the Digital Personal Data Protection Act, 2023 (DPDPA).

Fair Use: Avoid excessive or abusive polling of this endpoint. Implement appropriate caching strategies to minimize unnecessary API calls and respect rate limits imposed by the platform.

Terms of Service: Usage of this API is subject to the Surepass Terms of Service. Ensure your use case aligns with the permitted purposes outlined in your service agreement.

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-districts' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "state_name": "delhi" }'

{ "data": [ "Central", "East", "New Delhi", "North", "North East", "North West", "Shahdara", "South", "South East", "South West", "West" ], "status_code": 200, "message_code": "success", "message": "Success", "success": true }

Get District List

eCourts Case Number - List Districts#

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