Get SE State List

Endpoint Overview

GET /api/v1/se/state-code-list

Description

This API endpoint retrieves a comprehensive list of Indian states along with their corresponding state codes. It provides a standardized mapping between state names and their official two-letter codes, which is essential for address validation, form processing, and geographic data management in applications serving the Indian market.

Key Benefits

Simplifies address validation by providing official state codes

Ensures data consistency across your application's geographic references

Eliminates the need to maintain your own state code mapping database

Supports standardized data formatting for regulatory compliance

Use Cases

Financial Services

E-commerce

Government Services

KYC verification processes requiring standardized address information

Loan application forms with state-specific validation rules

Insurance policy issuance with geographic risk assessment

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

Request Body

This endpoint does not require a request body as it's a GET request that returns a static list of states and their codes.

Process Response

Response Parameters

Parameter	Type	Description
data	Array	List of state objects containing state names and their codes
data[].state	String	Full name of the Indian state
data[].state_code	String	Two-letter code representing the state
status_code	Integer	HTTP status code of the response (200 for success)
message_code	String	Status of the request ("success" for successful requests)
message	String	Human-readable message describing the result
success	Boolean	Indicates whether the request was successful

Example Successful Response

{
    "data": [
        {
            "state": "Delhi",
            "state_code": "DL"
        },
        {
            "state": "Haryana",
            "state_code": "HR"
        },
        {
            "state": "Jammu And Kashmir",
            "state_code": "JK"
        },
        {
            "state": "Karnataka",
            "state_code": "KR"
        },
        {
            "state": "Rajasthan",
            "state_code": "RJ"
        },
        {
            "state": "Telangana",
            "state_code": "TL"
        },
        {
            "state": "Uttarakhand",
            "state_code": "UK"
        },
        {
            "state": "Uttar Pradesh",
            "state_code": "UP"
        },
        {
            "state": "West Bengal",
            "state_code": "WB"
        }
    ],
    "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 token",
    "success": false
}

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

Implement token refresh mechanisms to handle token expiration gracefully

Use HTTPS for all API communications to ensure data privacy

Implement proper error handling for authentication failures

User Experience Guidelines

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

Implement dropdown menus with state selection to prevent user input errors

Sort states alphabetically in your UI for easier navigation

Consider implementing auto-complete functionality for state selection fields

Code Samples

cURL

Python

Node.js

Related APIs

SE Address Verification API - Validates addresses using state codes

SE State-wise Demographics API - Provides demographic data for Indian states

SE Geographic Boundaries API - Provides boundary information for Indian states

Compliance and Legal Considerations

When collecting and processing address information that includes state data, ensure compliance with India's Personal Data Protection laws. State codes should be used consistently across your application to maintain data integrity for regulatory reporting purposes.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": [ { "state": "Delhi", "state_code": "DL" }, { "state": "Haryana", "state_code": "HR" }, { "state": "Jammu And Kashmir", "state_code": "JK" }, { "state": "Karnataka", "state_code": "KR" }, { "state": "Rajasthan", "state_code": "RJ" }, { "state": "Telangana", "state_code": "TL" }, { "state": "Uttarakhand", "state_code": "UK" }, { "state": "Uttar Pradesh", "state_code": "UP" }, { "state": "West Bengal", "state_code": "WB" } ], "status_code": 200, "message_code": "success", "message": "Success", "success": true }

Get SE State List

Get SE State List#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Get SE State List

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples