District List

Endpoint Overview

GET /api/v1/land-verification/karnataka/district-list

GET /api/v1/land-verification/district-list

Both paths are valid and return identical responses. Use either interchangeably based on your integration preference.

Description

The Karnataka District List API provides a comprehensive, up-to-date enumeration of all administrative districts within the state of Karnataka, India. This endpoint serves as a foundational reference for land verification workflows by returning a standardized list of district names that can be used to validate user-submitted location data, populate district selection dropdowns, and route subsequent land-record queries to the correct regional authority.

Because district names must match exactly in downstream land-verification calls, consuming this endpoint ensures your application always uses canonical spellings—eliminating lookup failures caused by typos, inconsistent casing, or outdated district boundaries.

Key Benefits

Always Up-to-Date – Returns the current, authoritative list of Karnataka districts, including recently created districts such as Vijayanagara, so your application never relies on stale hard-coded data.

Validation Ready – Use the returned values as the allowed set for input validation, reducing bad requests to downstream land-record APIs.

Lightweight & Fast – A simple GET request with no required body parameters makes integration effortless and minimises latency in multi-step KYC or land-verification flows.

Consistent Naming – All district names follow a standardised lowercase format, enabling straightforward string matching across your data pipeline.

Use Cases

FinTech & Lending

Real Estate & PropTech

Government & Compliance

Pre-populate district dropdowns in loan-application forms to ensure borrowers select a valid Karnataka district before submitting collateral details.

Validate the district field in automated credit-underwriting pipelines when processing agricultural or property-backed loans.

Cross-check district data extracted from uploaded land documents against the canonical list to flag discrepancies before disbursal.

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

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.app

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

⚠️ Never expose your JWT token in client-side code or public repositories. Rotate tokens periodically and immediately if a token is suspected to be compromised.

Request Parameters

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token in the format `Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	No	Not required for this GET endpoint; omit or set to `application/json`

Request Body

This endpoint does not require a request body. Send an empty body or omit it entirely.

Parameter	Type	Required	Description
(none)	—	—	No request body parameters are required for this endpoint.

Example Request

{}

Process Response

Response Parameters

Parameter	Type	Description
`data`	`array of strings`	Ordered list of all Karnataka district names in lowercase. Each string represents one official district.
`status_code`	`integer`	HTTP-equivalent status code returned by the API (e.g., `200` for success).
`message_code`	`string`	Machine-readable status identifier (e.g., `"success"`). Use this for programmatic response handling.
`message`	`string`	Human-readable status message (e.g., `"Success"`). Suitable for logging or display.
`success`	`boolean`	Top-level flag indicating whether the request was fulfilled successfully. `true` on success, `false` on failure.

Example Successful Response

{
    "data": [
        "belagavi",
        "bagalkote",
        "vijayapura",
        "kalaburagi",
        "bidar",
        "raichur",
        "koppal",
        "gadag",
        "dharwad",
        "uttar kannada",
        "haveri",
        "ballari",
        "chitradurga",
        "davanagere",
        "shivamogga",
        "udupi",
        "chikkamagaluru",
        "tumakuru",
        "kolar",
        "bengaluru",
        "bangalore rural",
        "mandya",
        "hassan",
        "dakshina kannada",
        "kodagu",
        "mysore",
        "chamarajanagara",
        "chikkaballapur",
        "bengaluru south",
        "ramanagara",
        "yadagir",
        "vijayanagara"
    ],
    "status_code": 200,
    "message_code": "success",
    "message": "Success",
    "success": true
}

Possible Error Responses

401 Unauthorized

403 Forbidden

500 Internal Server Error

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

Returned when the Authorization header is missing, the JWT token is malformed, or the token has expired. Ensure you are using a valid token for the correct environment (sandbox vs. production).

Integration Best Practices

Security Recommendations

Use environment variables for storing JWT tokens—never hard-code credentials in source files or commit them to version control.

Separate sandbox and production tokens: maintain distinct token configurations for each environment to prevent accidental production calls during testing.

Implement token rotation: proactively refresh JWT tokens before expiry and handle 401 responses gracefully by triggering a re-authentication flow.

Restrict token scope: request only the permissions necessary for your use case. If your application only reads district lists, avoid issuing tokens with write or admin scopes.

Use HTTPS exclusively: both the sandbox and production base URLs enforce HTTPS. Never downgrade to HTTP.

User Experience Guidelines

Cache the response: the district list changes infrequently—cache results for at least 24 hours (or until your next application deployment) to reduce latency and API call volume.

Normalise for comparison: when matching user input against the returned district names, convert both sides to lowercase and trim whitespace, since all values in data are already lowercase.

Handle multi-word districts gracefully: several districts contain spaces (e.g., "uttar kannada", "bangalore rural"). Ensure your UI and validation logic accommodate multi-word strings.

Graceful degradation: if the API is temporarily unavailable, fall back to a locally cached district list so users can continue their workflow without interruption.

Provide clear error messages: if a user submits an unrecognised district name, surface a helpful message (e.g., "Please select a valid Karnataka district from the list") rather than a generic error.

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

Data Accuracy: District boundaries and names are defined by the Government of Karnataka. While this API reflects the current official list, developers should periodically re-fetch and update cached data to account for future administrative reorganisations (e.g., bifurcation or renaming of districts).

Data Usage: The district names returned by this endpoint are administrative identifiers. Their use in land-verification workflows may be subject to the Karnataka Land Revenue Act and related state regulations. Ensure your application's use case complies with applicable laws before processing any associated land-record data.

Personal Data: This endpoint does not return personal data. However, downstream land-verification APIs that accept a district as input may retrieve information linked to individuals. Handle all such data in accordance with India's Digital Personal Data Protection Act (DPDPA) and your organisation's data-handling policies.

Regulatory Compliance: If your organisation operates in sectors such as banking, insurance, or real estate, consult your compliance team to confirm that automated land-verification workflows meet RBI, IRDAI, or RERA guidelines as applicable.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": [ "belagavi", "bagalkote", "vijayapura", "kalaburagi", "bidar", "raichur", "koppal", "gadag", "dharwad", "uttar kannada", "haveri", "ballari", "chitradurga", "davanagere", "shivamogga", "udupi", "chikkamagaluru", "tumakuru", "kolar", "bengaluru", "bangalore rural", "mandya", "hassan", "dakshina kannada", "kodagu", "mysore", "chamarajanagara", "chikkaballapur", "bengaluru south", "ramanagara", "yadagir", "vijayanagara" ], "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