Get State List

Endpoint Overview

GET /api/v1/estamp/get-state-list

Description

The Get State List API provides a comprehensive list of all Indian states and union territories that are supported by Surepass's Estamp-related services. This endpoint serves as a foundational reference for developers who need to validate state information or populate dropdown menus in their applications when working with toll data queries and other Estamp functionalities.

This API returns standardized state identifiers in snake_case format, ensuring consistency across all Estamp-related operations. The endpoint is essential for applications that need to filter or categorize data by geographical regions within India's administrative boundaries.

Key Benefits

Complete Coverage: Access to all Indian states and union territories in a single API call

Standardized Format: Consistent snake_case naming convention for easy integration

Real-time Data: Always up-to-date list of supported regions for Estamp services

Lightweight Response: Fast and efficient endpoint with minimal payload overhead

Use Cases

Logistics & Transportation

Financial Services

Government & Public Sector

Toll Management Systems: Validate state information before processing toll data queries

Route Planning Applications: Filter available routes based on supported states

Fleet Management: Categorize vehicle operations by state for compliance tracking

Supply Chain Optimization: Analyze logistics costs and regulations by state

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.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token containing your JWT for API authentication
Content-Type	No	application/json (recommended for consistency)

Request Body

This endpoint does not require any request body parameters. It is a simple GET request that returns all available states.

Example Request

// No request body required for this endpoint
{}

Process Response

Response Parameters

Parameter	Type	Description
data	Array[String]	Array containing all supported state identifiers in snake_case format
status_code	Integer	HTTP status code indicating the result (200 for success)
message_code	String	Internal status code for the operation ("success" for successful requests)
message	String	Human-readable status message describing the result
success	Boolean	Indicates whether the API call was successful (true/false)

Example Successful Response

{
    "data": [
        "union_territory_of_daman_and_diu",
        "jammu_and_kashmir",
        "rajasthan",
        "tamil_nadu",
        "jharkhand",
        "tripura",
        "test_state",
        "bihar",
        "odisha",
        "karnataka",
        "uttarakhand",
        "national_capital_territory_of_delhi",
        "himachal_pradesh",
        "puducherry",
        "union_territory_administration_of_dadra_and_nagar_haveli_and_daman_and_diu",
        "manipur",
        "gujarat",
        "chhattisgarh",
        "chandigarh",
        "goa",
        "maharashtra",
        "uttar_pradesh",
        "meghalaya",
        "arunachal_pradesh",
        "assam",
        "punjab",
        "union_territory_of_ladakh",
        "andaman_and_nicobar",
        "andhra_pradesh"
    ],
    "status_code": 200,
    "message_code": "success",
    "message": "Success",
    "success": true
}

Possible Error Responses

Authentication Error

Server Error

{
    "status_code": 401,
    "message_code": "unauthorized",
    "message": "Invalid or expired authentication token",
    "success": false,
    "data": null
}

This error occurs when the JWT token is missing, invalid, or expired.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code or logs

Implement token refresh mechanisms to handle expired authentication

Use HTTPS only for all API communications to prevent token interception

Implement rate limiting on your end to avoid overwhelming the API

User Experience Guidelines

Cache the state list response to improve application performance and reduce API calls

Implement graceful error handling to provide meaningful feedback to users

Consider using the state list to pre-populate dropdown menus for better user experience

Sort states alphabetically in your UI for easier user navigation

Code Samples

cURL

Python

Node.js

Related APIs

Toll Data Query API: Use the state identifiers from this endpoint to filter toll-related queries by geographical region

Estamp Verification API: Validate Estamp documents using state-specific parameters

Geographic Data APIs: Additional location-based services that complement state-level information

Compliance and Legal Considerations

This API provides reference data for Indian states and union territories. Ensure your application handles the administrative boundaries correctly, especially for newly formed states or union territories. The "test_state" entry is for development purposes only and should not be used in production applications. Always validate state data against the most current list when processing official documents or legal transactions.

{ "data": [ "union_territory_of_daman_and_diu", "jammu_and_kashmir", "rajasthan", "tamil_nadu", "jharkhand", "tripura", "test_state", "bihar", "odisha", "karnataka", "uttarakhand", "national_capital_territory_of_delhi", "himachal_pradesh", "puducherry", "union_territory_administration_of_dadra_and_nagar_haveli_and_daman_and_diu", "manipur", "gujarat", "chhattisgarh", "chandigarh", "goa", "maharashtra", "uttar_pradesh", "meghalaya", "arunachal_pradesh", "assam", "punjab", "union_territory_of_ladakh", "andaman_and_nicobar", "andhra_pradesh" ], "status_code": 200, "message_code": "success", "message": "Success", "success": true }

Get State List

Get State List#

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

Get State List

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples