Sales Watch API: registration alerts for Tamil Nadu land

Example

Request

curl -X POST https://verified.realestate/api/v1/tools/sales_watch \
  -H "Authorization: Bearer $LANDLENS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"start","district_code":"03","taluk_code":"14","village_code":"196","register":"rural","survey_number":"65","sub_division":"4B","around":10,"label":"Kavanoor plot"}'

Responsereal answer

{
  "ok": true,
  "status": "proposal",
  "data": {
    "proposal": true,
    "action": "sales_watch_start",
    "label": "Watch the registrations around survey 65/4B",
    "params": {
      "district_code": "03",
      "taluk_code": "14",
      "village_code": "196",
      "register": "rural",
      "survey_number": "65",
      "sub_division": "4B",
      "around": 10,
      "label": "Kavanoor plot"
    },
    "cost": 0,
    "source": "Registration department encumbrance search, every week",
    "note": "Included in your enterprise plan (10 watches); nothing is charged."
  },
  "credits_charged": 0,
  "next": {
    "tool": "approve_action",
    "arguments": { "action": "sales_watch_start", "params": { "survey_number": "65", "sub_division": "4B", "...": "..." } }
  }
}

A real quote from the API, from an account on an enterprise plan with watches left, so cost is 0. Without one, cost is the monthly price. Trimmed for length.

What it returns

action decides the answer. list and read answer at once. start answers with a quote (status proposal); approve_action begins the watch in the background and job_status returns the new watch and its first search.

Field	What it holds
`watches[] (list)`	Every active watch on the account, each with its card fields below and new_deeds, the count of deeds found after the first search. plan_watches_left and price_per_month come with the list.
`watch (read)`	One watch: id, label, status, village, office (the sub registrar office searched), surveys, old_surveys, plan_included, credits_per_month, paid_until, next_search and url.
`searched_to, last_searched_at`	How far the register has been read, and when the last search ran.
`last_search_status, last_search_note`	Whether the last search succeeded, and the reason when it did not. A failed week is retried, never read as "no deeds".
`deeds[] (read)`	Up to 60 deeds, newest first: doc_no, date, nature, surveys, parties, extent, consideration, and new (false for the deeds the first 90-day search found).
`cancelled (cancel)`	true once the watch is stopped.

Ways to call it

One tool, four actions.

List your watches

Free. Every active watch with its last search and its count of new deeds.

{"action": "list"}

Read one watch

Free. The watch with every deed it has found.

{"action": "read","watch_id": 11}

Start a watch

A quote. Send the revenue codes and the survey number, and around for how many nearest surveys to add. A drawn polygon (up to 3 sq km) or a parcels list works instead; each village becomes its own watch.

{"action": "start","district_code": "03","taluk_code": "14","village_code": "196","survey_number": "65","sub_division": "4B","around": 10}

Cancel a watch

Stops the searches and the monthly charge. The month already begun is not refunded.

{"action": "cancel","watch_id": 11}

Inputs

The JSON body of the POST is the arguments. Only start needs land. The codes come free from resolve_parcel (a map point) or resolve_revenue_codes (names).

Argument	Type	What to send
`action`	string: list, read, start, cancel	What to do. Defaults to list.
`watch_id`	integer	For read and cancel.
`district_code`	string	Revenue district code (start).
`taluk_code`	string	Revenue taluk code (start).
`village_code`	string	Revenue village or town code (start).
`register`	string: rural, urban
`ward_code`	string	Town survey ward, for an urban parcel.
`block_code`	string	Town survey block, for an urban parcel.
`survey_number`	string	The property's own survey number (start).
`sub_division`	string
`around`	integer	How many of the nearest surveys in the same village to watch as well. Default 10; 0 for the property only.
`more_surveys`	array	Further survey numbers in the same village to watch, e.g. ["114", "115/2"].
`label`	string	A name for the watch, e.g. "Our plot at Muttukadu".
`polygon`	object	Instead of a survey (start): a GeoJSON Polygon drawn around the land, up to 3 sq km. Every plot inside is watched; plots in different villages become one watch each, each priced on its own.
`parcels`	array	Instead of a survey (start): plots chosen exactly, each {district_code, taluk_code, village_code, survey} (survey like "112/3A"; on village land the whole survey 112 is watched). One watch per village.

Code

Set LANDLENS_KEY to your key. In an AI app, connect https://verified.realestate/mcp once and ask in plain words instead. In Postman, download this API's collection, import it (File, Import) and set apiKey.

curl -X POST https://verified.realestate/api/v1/tools/sales_watch \
  -H "Authorization: Bearer $LANDLENS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"start","district_code":"03","taluk_code":"14","village_code":"196","register":"rural","survey_number":"65","sub_division":"4B","around":10,"label":"Kavanoor plot"}'

import os, requests

r = requests.post(
    "https://verified.realestate/api/v1/tools/sales_watch",
    headers={"Authorization": f"Bearer {os.environ['LANDLENS_KEY']}"},
    json={
        "action": "start",
        "district_code": "03",
        "taluk_code": "14",
        "village_code": "196",
        "register": "rural",
        "survey_number": "65",
        "sub_division": "4B",
        "around": 10,
        "label": "Kavanoor plot"
    },
    timeout=30,
)
body = r.json()
print(body["status"], body["credits_charged"], body["data"])

const res = await fetch("https://verified.realestate/api/v1/tools/sales_watch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LANDLENS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "action": "start",
    "district_code": "03",
    "taluk_code": "14",
    "village_code": "196",
    "register": "rural",
    "survey_number": "65",
    "sub_division": "4B",
    "around": 10,
    "label": "Kavanoor plot"
  }),
});
const body = await res.json();
console.log(body.status, body.credits_charged, body.data);

Watch survey 65/4B in Kavanoor village, Kundrathur taluk, and the ten surveys around it. Tell me whenever anything is sold or mortgaged there.

Your AI finds the village codes, shows you the monthly quote, and starts the watch only after you say yes.

Responses

Every answer has the same envelope. What status can say for this call:

status	What it means
`ok`	list, read or cancel answered.
`proposal`	The quote for a new watch. Nothing is charged. Approve it by sending next.arguments to approve_action within 30 minutes, unchanged.
`queued`	What approve_action answers (HTTP 202), with a job_id. job_status returns the watch and its first search when it is done.
`not_found`	No watch with that id on this account, or start was called without the codes and survey number (or a polygon or parcels).
`insufficient_credits`	HTTP 402 at approval, with the credits needed for the first month and your balance.

Where the data comes from

Register

The encumbrance index of the Tamil Nadu Registration Department, searched at the sub registrar office that holds the village.

Coverage

Every revenue village and town survey ward in Tamil Nadu. One watch covers up to 50 surveys in one village. On village land each survey is searched whole (every sub-division of 13 is survey 13). On town land the old survey numbers the town survey register prints for the watched plots are searched too.

How current

Weekly. The first search reads the last 90 days, so a watch starts with what already happened; each later search reads from where the previous one stopped, and a missed week is caught up.

How we read it

One encumbrance search per watch per week, over every survey in it together. A deed is new when it was not in the previous search. Each watch records when it was last searched, whether that search succeeded and, if not, why.

Who uses it

Land owners living away

Hear within a week if anyone registers a deed on your survey number, the usual first sign of an impersonation sale.

Lenders

Watch the land under a loan for a second mortgage or a sale registered behind the charge.

Developers and investors

Follow who is buying around a site, and at what consideration, week by week.

Limits and good practice

Tamil Nadu only.
A watch covers one village, up to 50 surveys. A polygon or parcels list across villages becomes one watch per village, each priced on its own.
The search runs weekly, on Monday. A deed shows once the sub registrar office has indexed it.
The WhatsApp digest goes to the phone number on the account. The API cannot send it elsewhere.
Cancelling stops further searches and charges; the month already paid is not refunded.

Pricing

Free to read, quoted to create

Listing and reading are free. A new watch costs 10 credits a month, taken at approval for the first month and then monthly while it runs. An enterprise plan includes a number of watches at no charge; the quote says which applies. Credits come from the same LandLens wallet as the chat and the minis. How billing works.

Calling at volume?

For thousands of calls a month, a portfolio sweep or a platform built on these registers, we quote a customised bulk price, with invoicing to match.

WhatsApp 99961 29996

Questions

Is there an API to get alerts when a property in Tamil Nadu is sold or mortgaged?

Yes, this one. A watch searches the registration department's encumbrance index every week over your survey and the surveys around it, and lists every newly registered deed.

How quickly will I know about a new registration?

Within a week of the office indexing the deed. The search runs every Monday.

Why watch the surveys around mine?

A deed can name a neighbouring survey or a different sub-division for the same ground. Watching the nearest surveys catches deeds that describe the land loosely, and shows what is selling next door.

What happens if a weekly search fails?

The watch records the failure in last_search_status and last_search_note, and the next run reads from where the last successful search stopped, so no week is skipped.

How much does it cost?

10 credits a month per watch, after a free quote. Reading and listing your watches are free.