Village List

Endpoint Overview

POST /api/v1/land-verification/karnataka/village-list

Description

The Karnataka Village List API provides a comprehensive, hierarchical listing of villages within a specified administrative region of Karnataka, India. By supplying a district, taluka, and hobli, developers can retrieve the complete list of villages that fall under that administrative subdivision.

This API is a foundational building block for land verification workflows in Karnataka. It enables applications to present accurate, government-aligned geographic data for downstream processes such as property record lookup, mutation verification, and RTC (Record of Rights, Tenancy and Crops) extraction. By anchoring subsequent land queries to a valid village name from an authoritative source, integrations can minimize errors caused by spelling variations or unofficial place names.

Key Benefits

Administrative Accuracy: Retrieves official village names as recognized by Karnataka's revenue administration hierarchy (District → Taluka → Hobli → Village).

Seamless Integration: Acts as a prerequisite step for other Karnataka land verification APIs, ensuring downstream requests use valid, government-recognized village identifiers.

Reduced Data Entry Errors: Empowers applications to offer dropdown/autocomplete selection instead of free-text village input, dramatically reducing typos and invalid queries.

Dual Environment Support: Available on both sandbox and production environments, allowing safe testing before live deployment.

Use Cases

Banking & Lending

Real Estate & PropTech

Government & Compliance

Validating the village associated with agricultural or rural property offered as loan collateral before initiating a land record check.

Populating village selection fields in digital loan origination systems for rural and semi-urban borrowers, ensuring alignment with revenue records.

Technical Implementation

Authentication

All API requests must be authenticated using a JWT Bearer Token. Follow these steps to authenticate:

Obtain API Credentials: Register on the Surepass platform to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token as per Surepass's token issuance process.

Include in Requests: Add the token to the Authorization header of every request using the format Bearer <your_token>.

Different base URLs and tokens apply for each environment:

Sandbox: https://sandbox.surepass.app — Use your sandbox JWT token for testing.

Production: https://kyc-api.surepass.app — Use your production JWT token for live operations.

⚠️ Never use a production token against the sandbox endpoint, or vice versa.

Request Parameters

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token for authentication. Format: `Bearer <JWT_TOKEN>`
`Content-Type`	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
`district`	String	Yes	The name of the district in Karnataka (e.g., `"belagavi"`). Must be in lowercase.
`taluka`	String	Yes	The name of the taluka within the specified district (e.g., `"belagavi"`). Must be in lowercase.
`hobli`	String	Yes	The name of the hobli within the specified taluka (e.g., `"kakati"`). Must be in lowercase.

Example Request

{
    "district": "belagavi",
    "taluka": "belagavi",
    "hobli": "kakati"
}

Process Response

Response Parameters

Parameter	Type	Description
`data`	Object	The main data object containing the query echo and result.
`data.district`	String	The district name echoed back from the request.
`data.taluka`	String	The taluka name echoed back from the request.
`data.hobli`	String	The hobli name echoed back from the request.
`data.village_list`	Array	An array of strings, each representing an official village name under the specified hobli.
`status_code`	Integer	HTTP-equivalent status code of the operation (e.g., `200` for success).
`message_code`	String	A machine-readable code representing the outcome (e.g., `"success"`).
`message`	String	A human-readable message describing the outcome (e.g., `"Success"`).
`success`	Boolean	`true` if the request was processed successfully, `false` otherwise.

Example Successful Response

{
    "data": {
        "district": "belagavi",
        "taluka": "belagavi",
        "hobli": "kakati",
        "village_list": [
            "kakati",
            "chandagada",
            "kedanura",
            "kabalapura",
            "kattanabhavi",
            "kanabargi",
            "ashte",
            "bambarage",
            "yamanapura",
            "agasage",
            "mannikeri",
            "chalavenahatti",
            "kadoli",
            "sutagatti",
            "haranakolla",
            "hudali",
            "bharamyanatti",
            "nandi",
            "panagutti",
            "gutti",
            "rangadolli",
            "honaga",
            "bhutaramahatti",
            "godyala",
            "muchchandi",
            "sonatti",
            "kalakhamba",
            "ningenahatti",
            "mhalenahatti",
            "kurihala b k",
            "gowndavada",
            "alatage",
            "bodakenatti",
            "handiganura",
            "halabhanvi",
            "heggeri",
            "parashyanatti",
            "ramadurga",
            "kurihala k ech",
            "kenchanatti"
        ]
    },
    "status_code": 200,
    "message_code": "success",
    "message": "Success",
    "success": true
}

Possible Error Responses

401 Unauthorized

400 Bad Request

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

Returned when the Authorization header is missing, malformed, or contains an expired/invalid JWT token. Verify your token and ensure it matches the target environment (sandbox vs. production).

Integration Best Practices

Security Recommendations

Never expose your JWT token in client-side code, public repositories, or logs. Always store tokens in secure server-side environment variables or a secrets manager.

Use environment-specific tokens: Maintain separate JWT tokens for sandbox and production environments. Never cross-use tokens between environments.

Implement token expiry handling: Monitor token expiration and implement automatic token refresh logic to avoid service interruptions in production.

Transmit over HTTPS only: All API calls must be made over HTTPS. Never send tokens or request payloads over unencrypted HTTP connections.

User Experience Guidelines

Use as a cascading dropdown: Trigger this API after the user selects a hobli (which itself should be populated from a prior taluka selection). Render the village_list array as a dropdown or searchable autocomplete field to guide users to valid entries.

Cache responses where appropriate: Village lists within a hobli change infrequently. Consider caching API responses for a reasonable TTL (e.g., 24 hours) to reduce latency and redundant API calls during a single user session.

Normalize input before sending: Convert district, taluka, and hobli values to lowercase before including them in the request body to avoid case-sensitivity issues.

Provide clear error messaging: If the API returns a 404 (no records found), inform users that the entered combination may be invalid and prompt them to recheck the selected district–taluka–hobli hierarchy.

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

Data Source Compliance: Village names returned by this API are sourced from Karnataka's official revenue administration records. Usage must comply with any terms of service imposed by the data source authority.

Data Privacy: While this API does not return personally identifiable information (PII), it is often used in conjunction with land verification APIs that may process sensitive property and identity data. Ensure your application complies with applicable Indian data protection laws, including the Digital Personal Data Protection Act, 2023 (DPDPA).

Purpose Limitation: This API should be used solely for legitimate land verification, KYC, lending, real estate, or government service purposes. Unauthorized bulk harvesting of geographic data may violate the API's terms of use.

Audit Trails: For regulated industries such as banking and insurance, maintain audit logs of API calls made as part of due-diligence or KYC workflows to satisfy regulatory record-keeping requirements.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/land-verification/karnataka/village-list' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "district": "belagavi", "taluka": "belagavi", "hobli": "kakati" }'

{ "data": { "district": "belagavi", "taluka": "belagavi", "hobli": "kakati", "village_list": [ "kakati", "chandagada", "kedanura", "kabalapura", "kattanabhavi", "kanabargi", "ashte", "bambarage", "yamanapura", "agasage", "mannikeri", "chalavenahatti", "kadoli", "sutagatti", "haranakolla", "hudali", "bharamyanatti", "nandi", "panagutti", "gutti", "rangadolli", "honaga", "bhutaramahatti", "godyala", "muchchandi", "sonatti", "kalakhamba", "ningenahatti", "mhalenahatti", "kurihala b k", "gowndavada", "alatage", "bodakenatti", "handiganura", "halabhanvi", "heggeri", "parashyanatti", "ramadurga", "kurihala k ech", "kenchanatti" ] }, "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