Get State List

Endpoint Overview

GET /api/v1/doctor/bds-mds/state-list

Description

The BDS/MDS State List API provides a comprehensive list of Indian states where dental practitioner (BDS/MDS) verification services are available. This endpoint serves as a prerequisite service that helps developers and applications determine the geographic scope of dental credential verification capabilities within the Surepass platform.

This API is essential for building dynamic user interfaces and implementing state-specific validation logic in healthcare verification systems. By fetching the current list of supported states, applications can ensure they only accept verification requests for jurisdictions where the service is available, thereby improving user experience and reducing failed verification attempts.

The endpoint returns state names in a standardized, lowercase format with underscores replacing spaces, making it easy to integrate with downstream verification APIs and database systems.

Key Benefits

Dynamic State Discovery: Retrieve real-time list of supported states without hardcoding values in your application

Improved UX: Build dropdown menus and selection interfaces that only show available options

Reduced Errors: Prevent verification requests for unsupported states, minimizing failed API calls

Easy Integration: Standardized state name format ensures seamless integration with other dental verification endpoints

Use Cases

Healthcare Platforms

HR & Recruitment

Regulatory & Compliance

Hospital Onboarding Systems: Medical facilities can use this API to populate state selection dropdowns when onboarding new dental practitioners, ensuring they only collect information for verifiable credentials

Telemedicine Platforms: Digital health platforms can dynamically display available states where dental practitioner verification is supported before initiating credential checks

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's a GET request that retrieves the state list without any input parameters.

Example Request

{}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container object holding the response data
data.state_list	Array[String]	Array of state names in lowercase with underscores (e.g., "andhra_pradesh", "maharashtra")
status_code	Integer	HTTP status code of the response (200 for success)
message_code	String	Machine-readable code indicating the result status ("success" for successful requests)
message	String	Human-readable message describing the response status
success	Boolean	Indicates whether the API request was successful (true/false)

Example Successful Response

{
  "data": {
    "state_list": [
      "maharashtra",
      "andhra_pradesh",
      "gujarat",
      "rajasthan"
    ]
  },
  "status_code": 200,
  "message_code": "success",
  "message": "Success",
  "success": true
}

Possible Error Responses

Unauthorized Access

Server Error

Rate Limit Exceeded

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

This error occurs when the JWT bearer token is missing, invalid, or expired. Verify that you're including the correct token in the Authorization header.

Integration Best Practices

Security Recommendations

Secure Token Storage: Never expose JWT tokens in client-side code or public repositories. Store tokens securely using environment variables or secure credential management systems

Token Rotation: Implement automatic token refresh mechanisms to maintain uninterrupted service and minimize security risks

HTTPS Only: Always use HTTPS endpoints to encrypt data in transit and prevent token interception

Access Control: Limit API access to authorized services only and implement IP whitelisting where possible

User Experience Guidelines

Cache State Lists: Cache the state list response with a reasonable TTL (e.g., 24 hours) to reduce API calls and improve application performance

Graceful Degradation: If the API is unavailable, have a fallback mechanism with a static list of common states to maintain functionality

Loading States: Display appropriate loading indicators while fetching the state list to inform users of ongoing processes

Error Messaging: Provide clear, user-friendly error messages when state list retrieval fails, guiding users on next steps

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

This API is designed to support healthcare credential verification in compliance with Indian medical and dental council regulations. When using this service, ensure that you have proper consent from the dental practitioners whose credentials are being verified. The state list is subject to change as Surepass expands its verification coverage. Always implement dynamic state fetching rather than hardcoding state lists to maintain compliance with the most current service availability. Data privacy regulations such as the Digital Personal Data Protection Act (DPDP) must be adhered to when handling practitioner information in conjunction with this API.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "state_list": [ "maharashtra", "andhra_pradesh", "gujarat", "rajasthan" ] }, "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