Get State List

Endpoint Overview

GET /api/v1/doctor/bhms/state-list

Description

The BHMS State List API provides a comprehensive list of Indian states where Bachelor of Homeopathic Medicine and Surgery (BHMS) doctor verification services are available. This endpoint returns all supported states in a standardized format, enabling seamless integration for healthcare verification platforms, medical staffing applications, and compliance management systems.

This API serves as a prerequisite for BHMS doctor verification workflows, allowing applications to dynamically display available states and ensure users select from supported jurisdictions before proceeding with verification requests.

Key Benefits

Dynamic State Discovery: Programmatically retrieve the current list of supported states without hardcoding values

Improved User Experience: Build dynamic dropdowns and selection interfaces with real-time availability

Future-Proof Integration: Automatically stay updated as new states are added to the verification service

Validation Support: Validate user inputs against the official list of supported states before submission

Use Cases

Healthcare Platforms

Staffing & Recruitment

Regulatory & Compliance

Hospital Onboarding Systems: Validate BHMS doctor registrations by first checking state availability before credential verification

Telemedicine Applications: Ensure doctors practicing in supported states can complete verification during platform registration

Medical Directory Services: Display accurate state coverage information for BHMS practitioner listings

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>`
Content-Type	Yes	Must be set to `application/json`

Request Body

This endpoint does not require a request body. It uses the GET method to retrieve the state list.

Example Request

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding the state list data
data.state_list	array[string]	Array of state identifiers in snake_case format representing supported states for BHMS verification
status_code	integer	HTTP status code of the response (200 for success)
message_code	string	Internal message code indicating the result status
message	string	Human-readable message describing the response status
success	boolean	Indicates whether the API call was successful (true/false)

Example Successful Response

{
    "data": {
        "state_list": [
            "west_bengal",
            "uttar_pradesh",
            "tamil_nadu",
            "chhattisgarh",
            "gujarat"
        ]
    },
    "status_code": 200,
    "message_code": "success",
    "message": "Success",
    "success": true
}

Possible Error Responses

Authentication Error

Server Error

Rate Limit Error

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

This error occurs when the Bearer token is missing, invalid, or has expired. Verify your JWT token and ensure it's properly included in the Authorization header.

Integration Best Practices

Security Recommendations

Secure Token Storage: Store JWT tokens securely using environment variables or secure vault services, never hardcode them in source code

Token Rotation: Implement automatic token refresh mechanisms to handle token expiration gracefully

HTTPS Only: Always use HTTPS endpoints to ensure encrypted communication and prevent token interception

Environment Separation: Maintain separate API tokens for sandbox and production environments to prevent accidental data mixing

User Experience Guidelines

Cache State Lists: Cache the state list response locally with appropriate TTL (Time To Live) to reduce API calls and improve application performance

Dynamic Dropdowns: Populate state selection dropdowns dynamically using the API response rather than hardcoding values

Loading States: Display loading indicators while fetching the state list to provide feedback during API calls

Error Handling: Implement graceful fallback mechanisms if the API is temporarily unavailable, such as showing a cached list with a warning

State Name Formatting: Convert snake_case state identifiers to proper display names (e.g., "west_bengal" → "West Bengal") for better readability

Code Samples

cURL

Python

Node.js

Related APIs

BHMS Doctor Verification API - Verify BHMS doctor credentials using registration numbers for the states retrieved from this endpoint

State-Specific Medical Council APIs - Query individual state medical council databases for detailed practitioner information

Doctor License Validation API - Cross-verify BHMS licenses against official state medical board records

Compliance and Legal Considerations

This API provides reference data for states where BHMS verification services are available. When implementing BHMS doctor verification workflows:

Data Privacy: Ensure compliance with applicable data protection regulations when collecting and processing doctor information

Consent Management: Obtain proper consent from doctors before initiating verification processes

Purpose Limitation: Use state list data only for legitimate verification and credentialing purposes

Audit Trails: Maintain logs of verification requests for compliance and dispute resolution

Regional Regulations: Be aware that medical licensing requirements vary by state; verification availability does not imply uniformity in regulatory standards

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "state_list": [ "west_bengal", "uttar_pradesh", "tamil_nadu", "chhattisgarh", "gujarat" ] }, "status_code": 200, "message_code": "success", "message": "Success", "success": true }

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