Toll State List

Endpoint Overview

GET /api/v1/nhai/toll-state-list

Description

The Toll State List API provides a comprehensive list of all Indian states and union territories available for NHAI (National Highways Authority of India) toll-related operations. This endpoint serves as a foundational reference for toll data queries, returning standardized state identifiers that can be used across various toll management systems and applications.

This API is essential for applications that need to display state selection options, validate geographic inputs, or filter toll data by geographical regions. It ensures consistency in state naming conventions across your toll management ecosystem.

Key Benefits

Complete Coverage: Returns all 36 states and union territories of India in a standardized format

Consistent Naming: Provides uniform state identifiers for seamless integration with other NHAI APIs

Real-time Data: Always returns the current list of available states for toll operations

Easy Integration: Simple GET request with no parameters required for quick implementation

Use Cases

Toll Management Systems

Fleet Management

Travel & Logistics

State-wise Toll Collection Reports: Generate comprehensive toll revenue reports filtered by specific states

Geographic Route Planning: Plan optimal routes considering toll plazas across different states

Compliance Monitoring: Track toll collection compliance across various state jurisdictions

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 for API authentication (JWT)
Content-Type	No	application/json (optional for GET requests)

Request Body

This endpoint does not require any request body parameters as it's 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	Object	Container object holding the response data
data.state_list	Array[String]	Array of state identifiers in snake_case format
status_code	Integer	HTTP status code (200 for successful requests)
message_code	String	Internal message code indicating request status
message	String	Human-readable response message
success	Boolean	Indicates whether the request was successful

Example Successful Response

{
    "data": {
        "state_list": [
            "andaman_and_nicobar_islands",
            "andhra_pradesh",
            "arunachal_pradesh",
            "assam",
            "bihar",
            "chandigarh",
            "chhattisgarh",
            "dadra_and_nagar_haveli_and_daman_and_diu",
            "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",
            "tripura",
            "uttar_pradesh",
            "uttarakhand",
            "west_bengal"
        ]
    },
    "status_code": 200,
    "message_code": "success",
    "message": "Success",
    "success": true
}

Possible Error Responses

Unauthorized Access

Server Error

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

Occurs when the JWT bearer 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 token expiration gracefully

Use HTTPS for all API communications to prevent token interception

Rotate API credentials regularly and monitor for unauthorized access

User Experience Guidelines

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

Implement proper error handling with user-friendly messages for network failures

Consider implementing offline functionality by storing the state list locally

Use the snake_case identifiers for backend processing but display human-readable names to users

Code Samples

cURL

Python

Node.js

Related APIs

NHAI Toll Plaza List API: Get detailed information about toll plazas in specific states

Toll Rate Calculator API: Calculate toll charges for specific routes using state data

Vehicle Registration Verification API: Verify vehicle details for toll exemption processing

Toll Transaction History API: Retrieve historical toll payment data filtered by state

Compliance and Legal Considerations

This API provides official NHAI state data for toll-related operations. Ensure compliance with Indian transportation regulations when using this data for commercial toll collection or route planning applications. The state identifiers returned are standardized for use across NHAI systems and should not be modified or translated without proper validation.

{ "data": { "state_list": [ "andaman_and_nicobar_islands", "andhra_pradesh", "arunachal_pradesh", "assam", "bihar", "chandigarh", "chhattisgarh", "dadra_and_nagar_haveli_and_daman_and_diu", "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", "tripura", "uttar_pradesh", "uttarakhand", "west_bengal" ] }, "status_code": 200, "message_code": "success", "message": "Success", "success": true }

Toll State List

Toll 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

Toll 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