LandLens API

Quickstart

1. Create a key. Sign in on LandLens with your phone number and open API keys on the dashboard. The key starts with llk_ and is shown once.
2. Check it works. GET /me returns your balance and what the key may spend. It is free.
3. Make a call. Every tool is POST /tools/{name} with its arguments as the JSON body. Start with a free one, such as finding the survey number at a map point.

# 1. who am I, and what is left
curl https://verified.realestate/api/v1/me -H "Authorization: Bearer $LANDLENS_KEY"

# 2. the parcel at a map point (free)
curl -X POST https://verified.realestate/api/v1/tools/resolve_parcel \
  -H "Authorization: Bearer $LANDLENS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat": 12.9010, "lng": 80.2279}'

The second call returns the survey number, village, taluk, district, the revenue codes the other tools take, the extent and the boundary. Most work starts there: the codes it returns feed the encumbrance, guideline value and FMB calls.

Authentication

Send the key in the Authorization header on every call: Authorization: Bearer llk_.... Keys belong to your LandLens account and spend from its wallet, personal or team.

Never put a key in a browser page or a mobile app. Call LandLens from your server and pass the answer on.

Making a call

Retries. Send an Idempotency-Key header (any string up to 255 visible characters) on calls you may retry. The first completed answer is kept for 24 hours and a repeat returns it again without running or charging. The same key with a different body is refused with 422, and one still running answers 409.

Timeouts. Most tools answer in about a second. Live government reads (an FMB sketch, a court register) usually take 5 to 30 seconds, and an approved CERSAI search about a minute, so allow 120 seconds. Work that runs longer is a long job and comes back at once with a job to poll.

The answer

Every call, paid or free, success or not, answers with the same envelope.

{
  "ok": true,
  "status": "ok",
  "data": { ... },
  "credits_quoted": 1,
  "credits_charged": 1,
  "credits_waived": 0,
  "balance_after": 4981,
  "request_id": "01M5HE65MX75473KSZSYXZC9PM"
}

Names and figures in data are as the government register publishes them. Say which register and the date the result carries, and never treat a name match as proof of identity.

Credits and billing

Calls spend LandLens credits from the same wallet as the chat and the minis. Each tool's price is in GET /tools (credits, and credits_max where the price depends on the arguments) and on its reference page.

Free calls have their own allowance: 600 an hour and 3,000 a day for an account that has bought credits, 12 an hour and 50 a day for one that has not, counted across every key and app on the account.

Quotes and approvals

A bigger job (an encumbrance pull, a CERSAI search, a certified copy) does not run on the first call. It answers "status": "proposal" with what it will do and what it costs, and a next block. Nothing is charged.

"next": {
  "tool": "approve_action",
  "arguments": { "action": "ec_transactions", "params": { ... } }
}

To go ahead, POST next.arguments to /tools/approve_action, unchanged, within 30 minutes. An edited or expired quote is refused. If the approval fails for a reason on our side, the same quote can be approved again without a second charge.

Long jobs

Work that reads a portal for minutes answers HTTP 202 with "status": "queued" and a poll block. POST its job_id to /tools/job_status every 30 to 60 seconds; data.status reads running until it ends in done or failed. A job's credit is held when it starts and returned if it fails.

Background work also carries a status_url: on a queued job, on each record of a queue_land_records batch, on an approved Verify My Land report and on a certified copy order. It shows the same answer as job_status (for a certified copy: processing, completed with the copy's link, or failed) and opens with no key or session, so you can hand it to a browser, a client or an AI app. It lasts 30 days.

A seller background check is polled the same way through /tools/seller_check_status with its check_id, about once a minute. It takes 8 to 15 minutes.

Webhooks

Rather than poll, add callback_url to the approve_action call of any queued action (an EC pull, a CERSAI search by property or by borrower). When the job is done or failed, we POST the same body job_status returns to that address, with "event": "job.completed", the job_id, its status, the data and sent_at.

The approval answer carries a webhook_secret, once; it is never shown again, including by job_status, so store it. Each delivery is signed: X-LandLens-Signature: sha256= followed by the hex HMAC-SHA256 of the raw body, keyed with that secret. Compare it before trusting the body. X-LandLens-Event and X-LandLens-Job name the event and the job.

# Python: check a delivery
import hmac, hashlib
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
ok = hmac.compare_digest(expected, request.headers["X-LandLens-Signature"])

Answer with any 2xx. Anything else is retried four more times, after 30 seconds, 2 minutes, 10 minutes and 30 minutes. Only a public https address of up to 500 characters is accepted; anything else is refused at approval with invalid_args and the quote stays open. Polling and the status_url keep working whatever happens to a delivery.

A CERSAI borrower search can carry up to 100 borrowers under one approval. The approval answers with the batch's job_id and item_job_ids; job_status on the batch lists each borrower with its status and verdict as it settles, and done of total.

Files

Tools that produce a document (an FMB sketch, a patta or A-register copy) return a link to it in a field ending in _url. The link opens without a key or a session, so you can hand it to a browser or an AI app as it is. It is signed for your account and lasts 7 days; after that, call the tool again for a fresh one.

Limits

Over the rate limit you get HTTP 429 and nothing is charged. A key's daily credit cap and a connected app's ceiling answer cap_reached once spent; free tools keep working.

The tools are for your own land and your clients' deals. Bulk harvesting of owner names is refused at the source, and a connection seen doing it is disconnected.

Errors

Read status rather than the HTTP code alone: several statuses share a code.

MCP and AI apps

The same tools are an MCP server at https://verified.realestate/mcp (Streamable HTTP). Add it as a custom connector in Claude, ChatGPT or Perplexity and sign in with your LandLens phone number; your AI then picks the right tool, says the price before a paid call and asks before approving a quote. Step-by-step setup for each app.

# Claude Code
claude mcp add --transport http landlens https://verified.realestate/mcp

# Codex
codex mcp add landlens --url https://verified.realestate/mcp

A coding agent can set itself up from the setup prompt.

Every tool

116 tools, 49 free. Those with a full reference page are linked; the rest are described in GET /tools. The 11 LandLens Intelligence tools come with the enterprise plan and are not listed here.