Hobli List

Endpoint Overview

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

Description

The Karnataka Hobli List API enables developers to retrieve a comprehensive list of hoblis (administrative sub-divisions) within a specified district and taluka in the state of Karnataka, India. A hobli is a revenue administrative unit in Karnataka, sitting below the taluka level and comprising a cluster of villages. This API is a critical building block for any land record verification, property due diligence, or rural administrative workflow that requires accurate geographical hierarchy data.

By supplying a valid district and taluka, the API returns a structured list of all hoblis under that jurisdiction — enabling downstream processes such as land parcel lookup, mutation record verification, and survey number validation to be scoped correctly.

Key Benefits

Accurate Administrative Scoping: Obtain the exact list of hoblis for any Karnataka district-taluka combination, ensuring downstream land queries are routed to the correct revenue jurisdiction.

Seamless Integration: Lightweight request payload and a clean, predictable JSON response make this API easy to integrate into existing KYC, fintech, or PropTech workflows.

Reduced Manual Effort: Eliminates the need for static hobli lookup tables or manual reference lookups, keeping your application current with authoritative data.

Foundation for Land Verification: Acts as the first step in multi-stage Karnataka land record workflows, feeding precise hobli identifiers into subsequent API calls for RTC, mutation, and encumbrance checks.

Use Cases

Banking & Lending

Real Estate & PropTech

Government & AgriTech

Populate hobli dropdowns in agricultural loan application forms to capture precise collateral land location before initiating RTC (Record of Rights, Tenancy and Crops) verification.

Validate that a borrower's self-reported hobli name is genuine and belongs to the correct district-taluka combination during property-backed loan underwriting.

Enable branch officers to correctly scope land record queries when processing Kisan Credit Card (KCC) or crop loan applications in rural Karnataka.

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

⚠️ Never share your JWT token or commit it to source control. Use environment variables or a secrets manager to inject tokens at runtime.

Request Parameters

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token in the format `Bearer <JWT_TOKEN>`. Use the sandbox token for the sandbox environment and the production token for the production environment.
`Content-Type`	Yes	Must be set to `application/json`.

Request Body

Parameter	Type	Required	Description
`district`	string	Yes	The name of the Karnataka district in lowercase (e.g., `"belagavi"`, `"mysuru"`, `"bengaluru"`).
`taluka`	string	Yes	The name of the taluka within the specified district, in lowercase (e.g., `"belagavi"`, `"hubballi"`, `"mangaluru"`).

Example Request

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

Process Response

Response Parameters

Parameter	Type	Description
`data`	object	Top-level wrapper object containing the result payload.
`data.district`	string	The district name as provided in the request, echoed back for confirmation.
`data.taluka`	string	The taluka name as provided in the request, echoed back for confirmation.
`data.hobli_list`	array of strings	An ordered list of hobli names belonging to the specified district and taluka. Each entry is a lowercase string.
`status_code`	integer	HTTP-style status code indicating the result of the request (e.g., `200` for success).
`message_code`	string	A machine-readable status identifier (e.g., `"success"`).
`message`	string	A human-readable status message (e.g., `"Success"`).
`success`	boolean	`true` if the request was processed successfully; `false` otherwise.

Example Successful Response

{
    "data": {
        "district": "belagavi",
        "taluka": "belagavi",
        "hobli_list": [
            "bagevadi",
            "kakati",
            "uchaganva",
            "belagavi"
        ]
    },
    "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 absent, the JWT token is malformed, or the token has expired. Ensure you are using the correct token for the target environment (sandbox vs. production).

Integration Best Practices

Security Recommendations

Store tokens in environment variables: Never hardcode your JWT Bearer token in application source code. Use .env files locally and a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault) in production.

Rotate tokens regularly: Implement token rotation policies to limit the blast radius of a compromised credential.

Use HTTPS exclusively: Always communicate with both the sandbox and production base URLs over TLS. Never downgrade to HTTP.

Restrict token scope: Where the Surepass platform supports it, issue tokens scoped only to the land verification endpoints your application requires.

Validate inputs server-side: Sanitize and validate district and taluka values on your backend before forwarding them to the API, to prevent injection or unintended queries.

User Experience Guidelines

Implement cascading dropdowns: Fetch the hobli list only after the user has selected both a district and a taluka, keeping the UI responsive and preventing premature API calls.

Normalize to lowercase: Since the API expects lowercase district and taluka names, normalize user input (e.g., "Belagavi" → "belagavi") before constructing the request payload.

Cache hobli lists strategically: Hobli boundaries change infrequently. Consider caching responses per district-taluka pair with a TTL of 24 hours or more to reduce API call volume and improve load times.

Handle empty hobli lists gracefully: Display a user-friendly message when hobli_list is empty rather than rendering a blank dropdown, and log the occurrence for investigation.

Provide a loading indicator: Since the API call is network-dependent, show a spinner or skeleton loader in the hobli dropdown while the request is in flight.

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

Data Use Policy: The hobli data returned by this API is sourced from Karnataka government revenue records. Ensure your application's usage complies with the terms of service agreed upon with Surepass and any applicable Karnataka government data sharing guidelines.

Personal Data: The Hobli List API does not request or return any personally identifiable information (PII). However, downstream APIs in land verification workflows may return sensitive land ownership details — handle such data in accordance with India's Digital Personal Data Protection Act, 2023 (DPDP Act).

Purpose Limitation: Use the API solely for the purposes declared during onboarding with Surepass (e.g., KYC, land verification, agricultural lending). Unauthorized repurposing of the data may violate the platform's terms of service.

Audit Trails: Maintain logs of API calls for audit and compliance purposes, especially in regulated industries such as banking, insurance, and government services. Ensure logs do not inadvertently capture Bearer tokens.

Sandbox vs. Production: The sandbox environment is strictly for development and testing. Do not process real customer data or live transactions 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/karnataka/hobli-list' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "district": "belagavi", "taluka": "belagavi" }'

{ "data": { "district": "belagavi", "taluka": "belagavi", "hobli_list": [ "bagevadi", "kakati", "uchaganva", "belagavi" ] }, "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