Taluka List

Endpoint Overview

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

Description

The Karnataka Taluka List API retrieves a comprehensive list of all talukas (sub-districts) within a specified district in Karnataka, India. This endpoint is part of the Surepass Land Verification suite and enables applications to programmatically access official administrative boundary data for Karnataka's revenue divisions.

Talukas are the fundamental administrative units used in Karnataka for land records, property registration, and revenue collection. Accurate taluka data is critical for land verification workflows, as every land parcel in Karnataka is uniquely identified within its taluka jurisdiction.

Key Benefits

Accurate Administrative Data: Returns the official list of talukas as recognized by Karnataka's revenue department, ensuring compliance with land record systems.

Seamless Integration: Simple POST request with a district name returns a structured list, making it easy to populate dropdowns, validate addresses, or drive downstream land-record queries.

Coverage Across Karnataka: Supports all districts in Karnataka, providing a single unified source for sub-district boundary data statewide.

Fast Lookups: Lightweight request/response structure ensures minimal latency, suitable for real-time user-facing applications.

Use Cases

FinTech & Lending

Real Estate & PropTech

Government & Legal Services

Validate borrower addresses during loan origination by confirming that the supplied taluka exists within the stated district before querying land records.

Pre-populate taluka selection dropdowns in digital loan application forms, reducing manual entry errors and improving customer experience.

Cross-check property location details during mortgage underwriting to ensure the collateral land parcel is correctly identified within the Karnataka revenue system.

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

⚠️ Important: Never share your JWT token or commit it to source control. Use environment variables to manage tokens securely across environments.

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 Karnataka district for which the taluka list is requested. Must be provided in lowercase (e.g., `"belagavi"`).

Example Request

{
    "district": "belagavi"
}

Process Response

Response Parameters

Parameter	Type	Description
`data`	object	The main data payload containing district information and the taluka list.
`data.district`	string	The district name as provided in the request.
`data.taluka_list`	array of strings	A list of all talukas within the specified district. Each entry is a lowercase string representing a taluka name.
`status_code`	integer	HTTP-equivalent status code indicating the result of the API call (e.g., `200` for success).
`message_code`	string	A machine-readable code summarizing the response outcome (e.g., `"success"`).
`message`	string	A human-readable message describing the response outcome (e.g., `"Success"`).
`success`	boolean	Indicates whether the request was processed successfully. `true` for a successful response, `false` otherwise.

Example Successful Response

{
    "data": {
        "district": "belagavi",
        "taluka_list": [
            "chikkodi",
            "athani",
            "raibag",
            "gokak",
            "hukkeri",
            "belagavi",
            "khanapur",
            "savadatti",
            "bailhongal",
            "ramadurg",
            "kittura",
            "nippani",
            "kagavada",
            "mudalagi",
            "yaragatti"
        ]
    },
    "status_code": 200,
    "message_code": "success",
    "message": "Success",
    "success": true
}

Possible Error Responses

Unauthorized (401)

Invalid Input (400)

Server Error (500)

{
    "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, the JWT token is malformed, or the token has expired. Ensure you are using a valid Bearer token for the correct environment (sandbox or production).

Integration Best Practices

Security Recommendations

Store tokens in environment variables: Never hard-code JWT tokens in source code. Use .env files or secrets managers (e.g., AWS Secrets Manager, HashiCorp Vault) to inject tokens at runtime.

Use separate tokens per environment: Maintain distinct JWT tokens for sandbox and production to prevent accidental data exposure or quota consumption.

Rotate tokens regularly: Periodically regenerate your JWT credentials and update your applications to limit the blast radius of a compromised token.

Enforce HTTPS: Always communicate with the API over HTTPS. Never transmit tokens or request payloads over unencrypted connections.

Restrict token permissions: Request only the minimum scopes required for your integration. Avoid using overly broad credentials for limited API interactions.

User Experience Guidelines

Cascade district → taluka selection: Design your UI so that the taluka dropdown is only enabled after the user has selected a district. Call this API on district selection to populate the taluka options dynamically.

Cache taluka lists client-side: Taluka data changes infrequently. Cache the response per district (e.g., for 24 hours) to reduce API calls and improve form responsiveness.

Normalize user input: Before sending the district value, convert it to lowercase and trim whitespace to avoid unnecessary errors.

Provide clear error feedback: If the API returns an error (e.g., invalid district), surface a user-friendly message such as "District not found. Please check your entry." rather than showing raw error codes.

Sort taluka lists alphabetically: Present the returned taluka_list in alphabetical order to make scanning easier for end users.

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

Data Usage: The taluka list data returned by this API is sourced from Karnataka's official revenue records. Ensure your application uses this data solely for legitimate land verification, address validation, or administrative purposes in compliance with applicable Indian laws.

Data Privacy: Although the taluka list itself does not contain personal information, downstream APIs in the land verification suite may return sensitive land ownership data. Ensure your data handling practices comply with the Information Technology Act, 2000, and any applicable state-level data privacy regulations.

Regulatory Compliance: If you are using this API as part of a KYC or due-diligence workflow, ensure your organization is compliant with RBI guidelines, PMLA (Prevention of Money Laundering Act), and any sector-specific regulatory requirements governing land verification.

API Terms of Service: Usage of this API is subject to the Surepass Terms of Service and API usage policies. Unauthorized redistribution or resale of the data obtained via this API is prohibited.

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/taluka-list' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "district": "belagavi" }'

{ "data": { "district": "belagavi", "taluka_list": [ "chikkodi", "athani", "raibag", "gokak", "hukkeri", "belagavi", "khanapur", "savadatti", "bailhongal", "ramadurg", "kittura", "nippani", "kagavada", "mudalagi", "yaragatti" ] }, "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