eCourts Case Number - List States

Endpoint Overview

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

Description

The eCourts Case Number - List States API retrieves a comprehensive list of all Indian states and union territories available within the eCourts ecosystem. This endpoint serves as a foundational lookup service that returns standardized state identifiers, which are required as input parameters for subsequent eCourts case-number-based search APIs.

The eCourts platform is India's nationwide digital infrastructure for court case information. Before performing any case lookup by case number, you must first identify the correct state jurisdiction. This API provides the canonical list of supported state and union territory codes in a machine-readable, snake_case format, ensuring consistency and accuracy across your integration pipeline.

Key Benefits

Comprehensive Coverage: Returns all 36 states and union territories of India supported by the eCourts system.

Standardized Identifiers: Provides snake_case formatted state codes ensuring uniformity across API calls in the eCourts workflow.

Zero Payload Simplicity: As a GET endpoint with no request body, integration is instantaneous with minimal overhead.

Foundation for Case Lookups: Acts as the essential first step in the eCourts case-number search workflow, enabling accurate jurisdiction selection.

Use Cases

Legal Technology

Financial Services & Lending

Compliance & Background Verification

Case Management Platforms: Populate state/jurisdiction dropdown menus dynamically for legal case search interfaces, ensuring the options always reflect the latest supported jurisdictions.

Legal Research Tools: Allow lawyers and paralegals to select the correct state before performing case number lookups, reducing search errors caused by incorrect jurisdiction selection.

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 the target environment (sandbox or production).

Request Body

This is a GET endpoint and does not require a request body. No query parameters are needed. Simply send an authenticated GET request to the endpoint.

Example Request

GET /api/v1/ecourts/case-number/list-state HTTP/1.1
Host: sandbox.surepass.app
Authorization: Bearer <your_jwt_token>

Process Response

Response Parameters

Parameter	Type	Description
`data`	Array of Strings	A list of all supported Indian states and union territories. These values are used as input identifiers in subsequent eCourts case search APIs.
`status_code`	Integer	HTTP status code of the response. `200` indicates a successful request.
`message_code`	String	Machine-readable message code representing the result status. `success` indicates the operation completed successfully.
`message`	String	Human-readable message describing the result of the API call.
`success`	Boolean	Indicates whether the API call was successful. `true` for success, `false` for failure.

Example Successful Response

{
  "data": [
    "andaman_and_nicobar",
    "andhra_pradesh",
    "arunachal_pradesh",
    "assam",
    "bihar",
    "chandigarh",
    "chhattisgarh",
    "delhi",
    "goa",
    "gujarat",
    "haryana",
    "himachal_pradesh",
    "jammu_and_kashmir",
    "jharkhand",
    "karnataka",
    "kerala",
    "ladakh",
    "lakshadweep",
    "madhya_pradesh",
    "maharashtra",
    "manipur",
    "meghalaya",
    "mizoram",
    "nagaland",
    "odisha",
    "puducherry",
    "punjab",
    "rajasthan",
    "sikkim",
    "tamil_nadu",
    "telangana",
    "the_dadra_and_nagar_haveli_and_daman_and_diu",
    "tripura",
    "uttar_pradesh",
    "uttarakhand",
    "west_bengal"
  ],
  "status_code": 200,
  "message_code": "success",
  "message": "Success",
  "success": true
}

Possible Error Responses

401 Unauthorized

403 Forbidden

500 Internal Server Error

{
  "data": null,
  "status_code": 401,
  "message_code": "unauthorized",
  "message": "Invalid or expired token. Please provide a valid JWT Bearer token.",
  "success": false
}

This error occurs when the Authorization header is missing, the token is malformed, or the JWT has expired. Regenerate your token and retry.

Integration Best Practices

Security Recommendations

Never expose JWT tokens in client-side code: Always make API calls from your backend server. Tokens embedded in frontend JavaScript or mobile app source code can be easily extracted and misused.

Rotate tokens periodically: Implement a token refresh mechanism to minimize exposure in case of a token leak. Do not use long-lived tokens in production environments.

Use HTTPS exclusively: All requests must be made over HTTPS. Never transmit tokens or API responses over unencrypted HTTP connections.

Restrict API key permissions: Apply the principle of least privilege — ensure your API credentials only have access to the eCourts endpoints your application requires.

User Experience Guidelines

Cache the state list: The list of states and union territories changes infrequently. Cache the response locally (e.g., for 24 hours) to reduce latency and avoid unnecessary API calls on every page load.

Format state names for display: The API returns snake_case identifiers (e.g., andhra_pradesh). Transform these into human-readable labels (e.g., "Andhra Pradesh") before rendering them in dropdown menus or UI components.

Provide search/filter functionality: With 36 entries, consider adding a search or type-ahead filter on your state selection UI to help users quickly find their target jurisdiction.

Pre-select based on context: If you already know the user's location or the state relevant to their query, pre-select it in the UI to streamline the workflow.

Code Samples

cURL

Python

Node.js

Related APIs

eCourts Case Number - List Districts: Retrieves the list of districts for a given state. Use a state value returned by this API as input to fetch its corresponding districts.

eCourts Case Number - List Court Complexes: Retrieves court complexes within a specific district and state, narrowing down the jurisdiction for case searches.

eCourts Case Number - Search: Performs the actual court case lookup using a case number, state, district, and court complex. This is the primary endpoint in the eCourts case-number workflow that this List States API supports.

Compliance and Legal Considerations

Data Source: The state and jurisdiction data is sourced from the eCourts (National Judicial Data Grid) platform maintained by the Government of India. Surepass acts as an authorized intermediary to provide programmatic access.

No Personal Data: This endpoint returns only a static list of Indian states and union territories. It does not process, transmit, or store any personally identifiable information (PII), and therefore does not fall under the purview of India's Digital Personal Data Protection Act (DPDPA) 2023 by itself.

Downstream Usage Compliance: While this endpoint is benign on its own, it is typically the first step in a court case lookup workflow. Ensure that your downstream use of eCourts data (e.g., case details, party names) complies with applicable data protection regulations, court data usage policies, and your organization's privacy policy.

Terms of Service: Usage of this API is subject to Surepass's Terms of Service and API usage agreements. 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 ********************

{ "data": [ "andaman_and_nicobar", "andhra_pradesh", "arunachal_pradesh", "assam", "bihar", "chandigarh", "chhattisgarh", "delhi", "goa", "gujarat", "haryana", "himachal_pradesh", "jammu_and_kashmir", "jharkhand", "karnataka", "kerala", "ladakh", "lakshadweep", "madhya_pradesh", "maharashtra", "manipur", "meghalaya", "mizoram", "nagaland", "odisha", "puducherry", "punjab", "rajasthan", "sikkim", "tamil_nadu", "telangana", "the_dadra_and_nagar_haveli_and_daman_and_diu", "tripura", "uttar_pradesh", "uttarakhand", "west_bengal" ], "status_code": 200, "message_code": "success", "message": "Success", "success": true }

Get State List

eCourts Case Number - List States#

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