Getting started
The LetsRealty Public API lets your own tools — a form builder, Zapier, a WhatsApp bot, a dialer, an AI assistant — read and write your agency's Leads, Inquiries and Activities, and hear about changes through webhooks. It is part of every plan, with the same limits for everyone.
All requests go to https://api.letsrealty.io, send and receive JSON, and carry an API Key.
1. Create an API Key
- Sign in to your admin console as a Tenant Admin.
- Open Integrations → API keys and choose Create key.
- Name it after the integration that will use it (the name shows as "via API: name" on everything it writes) and pick its scopes. To push Leads in,
leads:ingestis enough. - Copy the key. It looks like
lr_live_…and is shown only once; if you lose it, revoke it and create another.
Keep the key on a server. Anyone holding it can act for your agency within its scopes.
2. Make your first call
Send a Lead in with POST /v1/leads:ingest:
curl https://api.letsrealty.io/v1/leads:ingest \
-H "Authorization: Bearer $LETSREALTY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: form-submission-8841" \
-d '{
"source": "Website form",
"type": "inquiry",
"person": { "name": "Ana Rojas", "email": "ana@example.com", "phone": "+506 8888 1234" },
"message": "Is the house in Escazú still available?"
}'
The answer is 201 Created with the new Lead, or 200 OK if Ana was already a Lead (matched by email, then phone):
{
"lead": { "id": "6f1c…", "name": "Ana Rojas", "source": "api", "status": "new", "…": "…" },
"inquiry_id": "0b9e…",
"activity_id": null,
"warnings": []
}
The Lead now shows in your pipeline with its Inquiry, gets a Lead Owner and notifies your team exactly like a website inquiry.
3. Read it back
With a key that has leads:read:
curl https://api.letsrealty.io/v1/leads?limit=50 \
-H "Authorization: Bearer $LETSREALTY_API_KEY"
4. Read and pin a Lead's tier
Each Lead carries two tiers (hot, warm, moderate or cold):
score_tieris the AI's, with itsscoreandscore_reasoning. It isnullwhile the Lead is Unscored.tieris the Lead's tier: the tier a User pinned by hand when there is one, otherwisescore_tier. Sort and filter by this one; the console does.
While a tier is pinned, pinned_tier holds it, tier_pinned_by says who pinned it (the User's name, or "via API: key name") and tier_pinned_at when. Lead Scoring keeps updating score_tier underneath and never changes the pin.
With leads:write, pin a tier, or clear the pin with null:
curl -X PATCH https://api.letsrealty.io/v1/leads/$LEAD_ID \
-H "Authorization: Bearer $LETSREALTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"pinned_tier": "hot"}'
Pinning or clearing sends lead.updated with pinned_tier in changed_fields. It works whether or not Lead Scoring is on.
5. Close a Lead as lost, with why
Move a Lead to closed_lost with a lost_reason: other_agency, on_their_own, price, financing, property_unavailable, not_ready, unreachable, not_a_lead, or other with a lost_reason_note:
curl -X PATCH https://api.letsrealty.io/v1/leads/$LEAD_ID \
-H "Authorization: Bearer $LETSREALTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "closed_lost", "lost_reason": "price"}'
The reason is optional here: a Lead closed without one reads not_given. Leads carry lost_reason and lost_reason_note while they are closed_lost, and null otherwise; moving a Lead out of closed_lost clears them. A reason sent with any other status is refused (422).
Next steps
- Authentication & scopes — what each scope allows.
- Ingesting Leads — attribution, Properties, Agents and backfills.
- Webhooks — get told when a Lead arrives or changes.
- API reference — every operation and field. The raw OpenAPI 3.1 file is at /openapi.json.