Khata Number

Endpoint Overview

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

Description

The Uttarakhand Khata List API returns all available khata numbers for a specific village, tehsil, district, and Fasli year range in Uttarakhand, India. A khata (also known as a khewat or account number in revenue records) is a unique identifier assigned to a landowner or group of co-owners within a village's land register. It groups together all the individual plot (khasra) entries belonging to a particular owner or ownership group for a given record period.

This endpoint is the fifth level of the Surepass Land Verification metadata hierarchy — following the District List, Tehsil List, Village List, and Year List APIs — and provides the final selection parameter needed to retrieve detailed land ownership and khasra records. By exposing only the khata numbers that actually exist for the specified location and year, this API ensures downstream land record queries are always directed at valid, existing entries.

Key Benefits

Completes the Five-Level Metadata Chain: Supplies the khata numbers required as the final input parameter before fetching detailed land ownership and plot records, completing the full district → tehsil → village → year → khata selection flow.

Eliminates Invalid Record Queries: By returning only existing khata numbers for the specified location and year combination, the API prevents failed lookups caused by querying non-existent khata entries.

Enables Ownership-Level Navigation: Khata numbers are organized by landowner or ownership group, allowing applications to present users with owner-level record sets rather than requiring them to know specific plot numbers in advance.

Consistent Zero-Padded Format: Returns khata numbers in a consistent zero-padded string format (e.g., "00001"), matching the exact format expected by downstream land record verification endpoints without any additional transformation.

Use Cases

Real Estate

Banking & Finance

Legal & Compliance

Enable property buyers and agents to browse all khata entries for a selected village and year period, making it easy to identify and select the correct ownership record before retrieving detailed land parcel information.

Support title verification workflows by programmatically iterating over all khata numbers in a village to perform comprehensive ownership checks across an entire land register for a given Fasli period.

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. Obtain valid values from the Uttarakhand District List API.
tehsil	string	Yes	The name of the tehsil within the specified district, in lowercase (e.g., `"syalde"`). Obtain valid values from the Uttarakhand Tehsil List API.
village	string	Yes	The name of the village within the specified tehsil, in lowercase (e.g., `"ataliya"`). Obtain valid values from the Uttarakhand Village List API.
year	string	Yes	The Fasli year range for which khata numbers should be retrieved (e.g., `"1411-1416"`). Must be a valid year range for the specified village. Obtain valid values from the Uttarakhand Year List API.

Example Request

{
    "district": "almora",
    "tehsil": "syalde",
    "village": "ataliya",
    "year": "1411-1416"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains the district, tehsil, village, year, and the list of available khata numbers for the specified location and year.
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	string	The village name as provided in the request, echoed back in the response.
data.year	string	The Fasli year range as provided in the request, echoed back in the response.
data.khata_list	array of strings	A list of all available khata numbers for the specified location and year. Values are zero-padded numeric strings (e.g., `"00001"`, `"00035"`).
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": "ataliya",
        "year": "1411-1416",
        "khata_list": [
            "00001",
            "00002",
            "00003",
            "00004",
            "00005",
            "00006",
            "00007",
            "00008",
            "00009",
            "00010",
            "00011",
            "00012",
            "00013",
            "00014",
            "00015",
            "00016",
            "00017",
            "00018",
            "00019",
            "00020",
            "00021",
            "00022",
            "00023",
            "00024",
            "00025",
            "00026",
            "00027",
            "00028",
            "00029",
            "00030",
            "00031",
            "00032",
            "00033",
            "00034",
            "00035"
        ]
    },
    "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 missing, malformed, or contains an expired or invalid JWT token. Verify that you are supplying the correct Bearer token for the intended environment (sandbox or production) and that the token has not expired.

Integration Best Practices

Security Recommendations

Secure your JWT token at all times by storing it in environment variables or a dedicated secrets manager. Never embed tokens in client-side code, hardcode them in source files, or expose them in application logs or error messages.

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. Pairing a token with the wrong environment will cause authentication failures.

Rotate tokens regularly as a matter of policy, and revoke any token immediately if it is inadvertently exposed through logs, error traces, or version control.

Enforce HTTPS for all requests to ensure the Authorization header and all request/response payloads — including location identifiers and khata numbers — are encrypted in transit.

User Experience Guidelines

Trigger dynamically on year selection: Call this API automatically when a user selects a year range in your UI, and populate the khata selector with the returned khata_list — this completes the five-step guided selection flow and minimizes user effort.

Display khata numbers with context: Present khata numbers in a dropdown or searchable list labelled clearly as "Khata Number" or "Account Number (Khewat)" so users understand they are selecting a land ownership account, not a plot number.

Cache responses per location–year combination: Khata lists for a given district–tehsil–village–year combination are stable data. Cache results using a composite key for a reasonable duration (e.g., several hours) to avoid redundant calls when users navigate back through the selector.

Always bind input values from upstream APIs: Do not allow free-text entry for district, tehsil, village, or year fields — always populate these programmatically from the responses of the corresponding upstream metadata APIs to prevent invalid input errors.

Support search/filter for large lists: Some villages may have a large number of khata entries. Implement a searchable or filterable selector rather than a plain scrollable dropdown to keep the experience manageable when khata_list contains many entries.

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 metadata hierarchy and provides 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 valid tehsil values for a selected district.

Uttarakhand Village List — Returns all villages within a given district and tehsil. This is the third step in the hierarchy and provides valid village values required by this API.

Uttarakhand Year List — Returns all available Fasli year ranges for a given village. This is the fourth step in the hierarchy and provides valid year values required by this API.

Uttarakhand Land Record Verification — The primary land verification endpoint that uses the complete set of location parameters — district, tehsil, village, year, and khata number — to fetch detailed land ownership records.

Uttarakhand Khasra Details — Retrieves individual plot-level (khasra) information for a land parcel, using the district, tehsil, village, year, and khata number obtained through the full metadata hierarchy.

Compliance and Legal Considerations

This endpoint returns administrative metadata (khata numbers) and does not directly expose personally identifiable information (PII) or detailed land ownership records. However, khata numbers are closely linked to landowner identities in Uttarakhand's revenue records, and their use in conjunction with downstream land record endpoints may result in the processing of sensitive personal and property data. Ensure your application complies with the Digital Personal Data Protection Act (DPDPA) and the Uttarakhand Revenue Code when accessing and processing land record data. Obtain appropriate consent from individuals whose records are being accessed, limit data use to declared and consented purposes, and implement appropriate data minimization practices. The sandbox environment is strictly for development and testing — do not process real landowner data, property information, or live land record queries against the sandbox environment under any circumstances.

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

{ "data": { "district": "almora", "tehsil": "syalde", "village": "ataliya", "year": "1411-1416", "khata_list": [ "00001", "00002", "00003", "00004", "00005", "00006", "00007", "00008", "00009", "00010", "00011", "00012", "00013", "00014", "00015", "00016", "00017", "00018", "00019", "00020", "00021", "00022", "00023", "00024", "00025", "00026", "00027", "00028", "00029", "00030", "00031", "00032", "00033", "00034", "00035" ] }, "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