Village List

Endpoint Overview

POST /api/v1/land-verification/uttarakhand/meta/village-list

Description

The Uttarakhand Village List API returns a complete list of villages within a specified district and tehsil in Uttarakhand, India. This is the third and most granular level of the Surepass Land Verification metadata hierarchy — following the District List and Tehsil List APIs — and completes the district → tehsil → village cascading location chain that underpins all land record lookups in Uttarakhand.

Land records in Uttarakhand are maintained at the village level within a tehsil. Accurate village identification is therefore a prerequisite for fetching khasra details, ownership records, and other land verification data. By providing village names in the precise format expected by downstream land verification endpoints, this API eliminates manual data entry errors and ensures seamless integration with the broader Surepass land record ecosystem.

Key Benefits

Completes the Location Hierarchy: Serves as the final step in the district → tehsil → village cascading selector, enabling precise land parcel identification required for all subsequent land record queries.

Authoritative Village Data: Returns village names in the exact lowercase format accepted by Surepass land verification endpoints, preventing mismatches that could result in failed or incorrect record lookups.

Comprehensive Coverage: Provides exhaustive village lists per tehsil — including smaller settlements — ensuring no valid land parcel falls outside the scope of your application.

Reduced Integration Complexity: Eliminates the need to maintain and update static village datasets per tehsil, keeping your application in sync with the official administrative structure without manual effort.

Use Cases

Real Estate

Banking & Finance

Legal & Compliance

Build a fully guided, three-level location picker (district → tehsil → village) in property listing and search platforms, ensuring users can only submit valid location combinations for Uttarakhand land record queries.

Validate village names in property documents or sale deeds against the official list during title verification to flag discrepancies before proceeding with due diligence.

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 authentication. Format: `Bearer <JWT_TOKEN>`
Content-Type	Yes	Must be set to `application/json` as the endpoint expects a JSON request body.

Request Body

Parameter	Type	Required	Description
district	string	Yes	The name of the district in lowercase (e.g., `"almora"`). Must be a valid Uttarakhand district name. Use the Uttarakhand District List API to obtain valid values.
tehsil	string	Yes	The name of the tehsil within the specified district, in lowercase (e.g., `"syalde"`). Must be a valid tehsil for the given district. Use the Uttarakhand Tehsil List API to obtain valid values.

Example Request

{
    "district": "almora",
    "tehsil": "syalde"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains the district name, tehsil name, and the list of villages within that tehsil.
data.district	string	The district name as provided in the request, echoed back in the response.
data.tehsil	string	The tehsil name as provided in the request, echoed back in the response.
data.village_list	array of strings	A complete list of all village names within the specified district and tehsil, returned in lowercase format.
status_code	integer	HTTP-equivalent status code for the response. `200` indicates success.
message_code	string	A machine-readable status indicator. `"success"` on successful responses.
message	string	A human-readable status message. `"Success"` on successful responses.
success	boolean	`true` if the request was processed successfully; `false` otherwise.

Example Successful Response

{
    "data": {
        "district": "almora",
        "tehsil": "syalde",
        "village_list": [
            "ataliya",
            "afalkhola",
            "afaun",
            "agaspur",
            "amkhet",
            "ekoraula",
            "ugliaseem",
            "udepur",
            "uprari",
            "ararirajwar",
            "arari bist",
            "okhal bhakal",
            "okhalyun",
            "kankote",
            "kanmunga",
            "kanari thor",
            "kanari kheel",
            "kanyal bakhal",
            "kafalgaon",
            "kafal gair",
            "kafaltana",
            "kaman",
            "kamet pani",
            "kaljhipa joshi",
            "kaljhipa rajwar",
            "kalia ligune",
            "kalyanpur",
            "karchuli bagar",
            "kimbagarh",
            "kumaleshwar",
            "kulsira",
            "kusiyachaun talla",
            "kusiyachaun malla",
            "kelani",
            "kainhargaon",
            "kotesari",
            "kotha",
            "khatalgoan",
            "khatal gair",
            "khadaku bhanriya ",
            "kharik dang",
            "khalyun",
            "garasari",
            "garhwal bakhal ",
            "gajar",
            "garhakhet",
            "gewaipani",
            "gudlekh",
            "gumati",
            "gairkhet",
            "goghyanibasiseem",
            "golana",
            "gangajhala pokhal",
            "gawal beena",
            "gwali",
            "gwaligaon talli malli",
            "ghanyal",
            "ghaniyal palla",
            "ghaniyal walla",
            "ghugti chak armoli",
            "ghughati",
            "chuck aawla",
            "chuck dhanpur",
            "chakh pantgaon",
            "chak patal",
            "chakkar goan",
            "chachroti",
            "chanoli talli malli",
            "chantar khari",
            "talli chamyari",
            "chamyadi malli",
            "chacha qurali",
            "chichoan",
            "chitphanda",
            "churain gouth",
            "chauna",
            "chhayani",
            "ghhipa",
            "janarkhani",
            "jalotia",
            "jashkote",
            "jaspur",
            "jalikhan",
            "junoya",
            "jaikhal",
            "bagarh",
            "jhejakote",
            "jhipa jabar",
            "titari",
            "dathiwalli",
            "dungari",
            "dotiyalbakhal",
            "dove chak",
            "dhika",
            "dhayakichar",
            "dhondiyual bakhal",
            "talla matela",
            "talai",
            "talya chak",
            "talla khalduwa",
            "talla dhaneta",
            "kanhayni talli",
            "talli chintoli",
            "talli mahroli",
            "tamadhaun",
            "taleshwar",
            "timili",
            "timiltanola",
            "tuni bakhal",
            "tolbudhani",
            "dudhauri birkhal",
            "dubsil",
            "dharkot",
            "nagar kotia",
            "nagargaon",
            "nimugair",
            "newalgaon",
            "nail",
            "nehalgair",
            "naugaon",
            "naugaun chak majheda",
            "pacharuwa kainhargaon",
            "pacharuwa tamadhaun",
            "patal gaon",
            "patwal bakhal",
            "patthar khola",
            "paparia",
            "panpnaula",
            "payalgaon",
            "parathola",
            "paharpani",
            "palpur",
            "paleetya",
            "pipalkote",
            "pitangovakhal ",
            "pipalkhal",
            "pipaura",
            "pilkhi",
            "peepalgoan",
            "pungiri chak vetandhaar ",
            "paithana",
            "phania",
            "fulangchak ",
            "futikuda",
            "bajar khora",
            "babalia",
            "barahkhal",
            "bawari kichar",
            "basanalgaon",
            "basbhira",
            "basisim",
            "bajkhet",
            "bisarakhet",
            "buraspani",
            "bairsal",
            "bohragaon",
            "bauli khalyari",
            "barangal",
            "bhanriakali",
            "bhanaria nata",
            "bhanaria pati",
            "bharsoli",
            "bhakura talla",
            "bhakura malla",
            "bheti",
            "bhawar lagga palpur",
            "bhelipar",
            "bheliwar",
            "bhaidgaon",
            "bhaisora",
            "bhaunlekh",
            "mangaru khal",
            "matakhani",
            "malla matela",
            "mayalgaon",
            "malkhora chak ulakhyo",
            "malla khalduwa",
            "malla dhaneta",
            "malli chamyart",
            "malli mahroli",
            "masmoli",
            "masaur",
            "mahgyari",
            "talla mahargaon",
            "malla mahargaon",
            "munyarhi",
            "musalkanda",
            "maunidhaya",
            "ratkhet",
            "ramsingh kichar",
            "rikhon",
            "ritha khalyo",
            "rudholi",
            "rotapani",
            "rodiyal bakhal",
            "lakharkote",
            "lambari",
            "lal nagari",
            "lauwal bakhal",
            "bansari",
            "wal mara",
            "basai",
            "birot",
            "betandhar",
            "bisar dhaya",
            "bhanaria seru",
            "saterh",
            "shadigaon",
            "sade",
            "sanar bhira",
            "sarai khet",
            "saskhet",
            "sarsoan",
            "simal gwina",
            "simgoan",
            "sunoli",
            "surmoli",
            "sera",
            "sali patli",
            "sait dunga chak",
            "saugarh",
            "hansali",
            "hulang bagar",
            "hansa bhanariya "
        ]
    },
    "status_code": 200,
    "message_code": "success",
    "message": "Success",
    "success": true
}

Possible Error Responses

Unauthorized

Invalid Input

{
    "data": null,
    "status_code": 401,
    "message_code": "unauthorized",
    "message": "Authentication credentials were not provided or are invalid.",
    "success": false
}

Returned when the Authorization header is absent, malformed, or contains an invalid or expired JWT token. Ensure you are using the correct Bearer token for the target environment (sandbox or production) and that the token has not expired.

Integration Best Practices

Security Recommendations

Secure your JWT token by storing it in environment variables or a dedicated secrets manager. Never embed tokens directly in source code or expose them in client-side applications.

Use environment-specific tokens: The sandbox JWT token must only be used with https://sandbox.surepass.app, and the production JWT token must only be used with https://kyc-api.surepass.app. Cross-environment token usage will result in authentication failures.

Rotate tokens proactively on a regular schedule and revoke any token that may have been inadvertently exposed in logs, error messages, or version control.

Always use HTTPS to ensure that the Authorization header and all request/response payloads, including village data, are encrypted in transit.

User Experience Guidelines

Trigger dynamically on tehsil selection: Call this API automatically when a user selects a tehsil in your UI, and populate the village dropdown with the returned village_list — this creates a smooth, guided three-level location selection experience.

Cache responses per district–tehsil pair: Village lists are stable administrative data. Cache results keyed by a district:tehsil composite key (e.g., for several hours) to reduce API calls and improve dropdown responsiveness for frequently accessed combinations.

Normalize input to lowercase: Always convert user-supplied or programmatically derived district and tehsil values to lowercase before sending the request, as the API expects values in the same format returned by the District List and Tehsil List APIs.

Handle large lists gracefully: Some tehsils contain hundreds of villages. Implement a searchable or filterable dropdown (with type-ahead/autocomplete) rather than a plain scrollable list to keep the UX manageable when village_list is large.

Show loading indicators: Since this call is triggered by a user interaction (tehsil selection), display a loading state in the village selector while the response is being fetched to prevent confusion or duplicate submissions.

Code Samples

cURL

Python

Node.js

Related APIs

Uttarakhand District List — Retrieves the complete list of districts in Uttarakhand. This is the first step in the location hierarchy and provides the valid district values required by this API.

Uttarakhand Tehsil List — Returns all tehsils within a given district. This is the second step in the hierarchy and provides the valid tehsil values required by this API.

Uttarakhand Land Record Verification — The primary land verification endpoint that uses the district, tehsil, and village values — obtained via the metadata APIs — to fetch and verify land ownership records.

Uttarakhand Khasra Details — Retrieves plot-level (khasra) information for a specific land parcel, identified using the district, tehsil, village, and khasra number obtained from the metadata hierarchy.

Compliance and Legal Considerations

This endpoint returns administrative metadata only (village names) and does not expose personally identifiable information (PII) or sensitive land ownership records. However, it is an integral part of the Surepass Uttarakhand Land Verification suite, which interfaces with state revenue land data governed by the Uttarakhand Revenue Code and applicable Indian land administration legislation. When using downstream land record endpoints in conjunction with this metadata API, ensure your application complies with the Digital Personal Data Protection Act (DPDPA), obtains appropriate consent from individuals whose land records are being accessed, and limits data use to the purposes for which consent was granted. The sandbox environment is strictly for development and testing — do not process real personal data, property information, or live land record queries in the sandbox.

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/uttarakhand/meta/village-list' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "district": "almora", "tehsil": "syalde" }'

{ "data": { "district": "almora", "tehsil": "syalde", "village_list": [ "ataliya", "afalkhola", "afaun", "agaspur", "amkhet", "ekoraula", "ugliaseem", "udepur", "uprari", "ararirajwar", "arari bist", "okhal bhakal", "okhalyun", "kankote", "kanmunga", "kanari thor", "kanari kheel", "kanyal bakhal", "kafalgaon", "kafal gair", "kafaltana", "kaman", "kamet pani", "kaljhipa joshi", "kaljhipa rajwar", "kalia ligune", "kalyanpur", "karchuli bagar", "kimbagarh", "kumaleshwar", "kulsira", "kusiyachaun talla", "kusiyachaun malla", "kelani", "kainhargaon", "kotesari", "kotha", "khatalgoan", "khatal gair", "khadaku bhanriya ", "kharik dang", "khalyun", "garasari", "garhwal bakhal ", "gajar", "garhakhet", "gewaipani", "gudlekh", "gumati", "gairkhet", "goghyanibasiseem", "golana", "gangajhala pokhal", "gawal beena", "gwali", "gwaligaon talli malli", "ghanyal", "ghaniyal palla", "ghaniyal walla", "ghugti chak armoli", "ghughati", "chuck aawla", "chuck dhanpur", "chakh pantgaon", "chak patal", "chakkar goan", "chachroti", "chanoli talli malli", "chantar khari", "talli chamyari", "chamyadi malli", "chacha qurali", "chichoan", "chitphanda", "churain gouth", "chauna", "chhayani", "ghhipa", "janarkhani", "jalotia", "jashkote", "jaspur", "jalikhan", "junoya", "jaikhal", "bagarh", "jhejakote", "jhipa jabar", "titari", "dathiwalli", "dungari", "dotiyalbakhal", "dove chak", "dhika", "dhayakichar", "dhondiyual bakhal", "talla matela", "talai", "talya chak", "talla khalduwa", "talla dhaneta", "kanhayni talli", "talli chintoli", "talli mahroli", "tamadhaun", "taleshwar", "timili", "timiltanola", "tuni bakhal", "tolbudhani", "dudhauri birkhal", "dubsil", "dharkot", "nagar kotia", "nagargaon", "nimugair", "newalgaon", "nail", "nehalgair", "naugaon", "naugaun chak majheda", "pacharuwa kainhargaon", "pacharuwa tamadhaun", "patal gaon", "patwal bakhal", "patthar khola", "paparia", "panpnaula", "payalgaon", "parathola", "paharpani", "palpur", "paleetya", "pipalkote", "pitangovakhal ", "pipalkhal", "pipaura", "pilkhi", "peepalgoan", "pungiri chak vetandhaar ", "paithana", "phania", "fulangchak ", "futikuda", "bajar khora", "babalia", "barahkhal", "bawari kichar", "basanalgaon", "basbhira", "basisim", "bajkhet", "bisarakhet", "buraspani", "bairsal", "bohragaon", "bauli khalyari", "barangal", "bhanriakali", "bhanaria nata", "bhanaria pati", "bharsoli", "bhakura talla", "bhakura malla", "bheti", "bhawar lagga palpur", "bhelipar", "bheliwar", "bhaidgaon", "bhaisora", "bhaunlekh", "mangaru khal", "matakhani", "malla matela", "mayalgaon", "malkhora chak ulakhyo", "malla khalduwa", "malla dhaneta", "malli chamyart", "malli mahroli", "masmoli", "masaur", "mahgyari", "talla mahargaon", "malla mahargaon", "munyarhi", "musalkanda", "maunidhaya", "ratkhet", "ramsingh kichar", "rikhon", "ritha khalyo", "rudholi", "rotapani", "rodiyal bakhal", "lakharkote", "lambari", "lal nagari", "lauwal bakhal", "bansari", "wal mara", "basai", "birot", "betandhar", "bisar dhaya", "bhanaria seru", "saterh", "shadigaon", "sade", "sanar bhira", "sarai khet", "saskhet", "sarsoan", "simal gwina", "simgoan", "sunoli", "surmoli", "sera", "sali patli", "sait dunga chak", "saugarh", "hansali", "hulang bagar", "hansa bhanariya " ] }, "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