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

  1. Sign in to your admin console as a Tenant Admin.
  2. Open Integrations → API keys and choose Create key.
  3. 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:ingest is enough.
  4. 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_tier is the AI's, with its score and score_reasoning. It is null while the Lead is Unscored.
  • tier is the Lead's tier: the tier a User pinned by hand when there is one, otherwise score_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