Year List

Endpoint Overview

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

Description

The Uttarakhand Year List API returns the available land record years (Fasli years) for a specific village within a given district and tehsil in Uttarakhand, India. This is the fourth and final level of the Surepass Land Verification metadata hierarchy — following the District List, Tehsil List, and Village List APIs — and completes the district → tehsil → village → year selection chain required before fetching actual land records.

Land records in Uttarakhand are historically organized by Fasli year ranges (the agricultural calendar used in Indian revenue administration). Different villages may have records available for different year ranges, and some may also include a special record set identified by the value "999". By exposing only the year ranges for which records actually exist in a given village, this API prevents unnecessary queries against non-existent record sets and enables applications to present users with only valid year options for their selected location.

Key Benefits

Completes the Metadata Hierarchy: Serves as the final step in the four-level location and year selector (district → tehsil → village → year), ensuring that land record queries are always directed at a valid, existing dataset.

Prevents Invalid Queries: Exposes only the year ranges for which records exist in the specified village, eliminating failed lookups caused by querying unavailable Fasli year ranges.

Supports Historical Record Access: By returning multiple year range options per village, this API enables applications to support historical land record research and ownership timeline analysis.

Consistent Format: Returns year range values in the exact format accepted by downstream land record verification endpoints, ensuring compatibility without additional transformation.

Use Cases

Real Estate

Banking & Finance

Legal & Compliance

Enable property buyers and agents to select the relevant land record year when verifying historical ownership for a specific village parcel, supporting comprehensive title due diligence.

Power a guided four-step property verification form (district → tehsil → village → year) that only presents valid year options, reducing user errors and failed lookups.

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. 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"`). Use the Uttarakhand Tehsil List API to obtain valid values for the given district.
village	string	Yes	The name of the village within the specified tehsil, in lowercase (e.g., `"ataliya"`). Use the Uttarakhand Village List API to obtain valid values for the given district–tehsil combination.

Example Request

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

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains the district, tehsil, village, and available year list for the specified location.
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_list	array of strings	A list of available Fasli year ranges for which land records exist in the specified village. Values are formatted as year range strings (e.g., `"1411-1416"`) or the special value `"999"`.
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_list": [
            "1411-1416",
            "1417-1422",
            "1423-1428",
            "999"
        ]
    },
    "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 and that it corresponds to the intended environment (sandbox or production).

Integration Best Practices

Security Recommendations

Protect your JWT token by storing it in environment variables or a secrets manager. Never hardcode tokens in application source code or expose them in client-side bundles or logs.

Use environment-specific tokens: The sandbox JWT token must only be paired with https://sandbox.surepass.app, and the production JWT token must only be used with https://kyc-api.surepass.app. Mismatching tokens and environments will cause authentication errors.

Rotate tokens on a regular schedule and immediately revoke any token that may have been accidentally exposed through error messages, logs, or version control history.

Transmit all requests over HTTPS to protect the Authorization header and all request/response data — including location identifiers — from interception.

User Experience Guidelines

Trigger dynamically on village selection: Call this API automatically when a user selects a village in your UI, and populate the year selector with the returned year_list — this creates a seamless four-step guided location and year selection experience.

Display year ranges clearly: Present Fasli year range strings (e.g., "1411-1416") to users with appropriate context — consider labeling the dropdown as "Record Period" or "Fasli Year Range" so users understand they are selecting a historical land record period, not a Gregorian calendar year.

Handle the "999" value explicitly: The special value "999" in year_list may represent a specific record type or undated record set. Display it with a descriptive label in your UI (e.g., "Other / Undated Records") to avoid user confusion.

Cache responses per district–tehsil–village combination: Year lists are stable data. Cache results keyed by the composite district:tehsil:village identifier for a reasonable duration (e.g., several hours) to avoid redundant API calls when users navigate back and forth through the location selector.

Always pass exact values from previous metadata API responses: Do not allow free-text input for district, tehsil, or village fields in this request — always bind them to values returned by the corresponding upstream metadata APIs to prevent invalid input errors.

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 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 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 Land Record Verification — The primary land verification endpoint that uses the district, tehsil, village, and year values — all 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, using the complete district, tehsil, village, year, and khasra number obtained through the metadata hierarchy.

Compliance and Legal Considerations

This endpoint returns administrative metadata only (available Fasli year ranges) and does not expose personally identifiable information (PII) or sensitive land ownership records directly. 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 this API in conjunction with downstream land record endpoints, ensure your application complies with the Digital Personal Data Protection Act (DPDPA), obtains appropriate consent from individuals whose historical land records are being accessed, and limits data processing to explicitly stated and consented purposes. The sandbox environment is strictly for development and testing — do not submit real personal data, property information, or production land record queries in the sandbox environment.

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

{ "data": { "district": "almora", "tehsil": "syalde", "village": "ataliya", "year_list": [ "1411-1416", "1417-1422", "1423-1428", "999" ] }, "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