Primeros pasos
La API pública de LetsRealty permite que tus propias herramientas —un creador de formularios, Zapier, un bot de WhatsApp, un marcador telefónico, un asistente de IA— lean y escriban los Leads, consultas y actividades de tu agencia, y se enteren de los cambios mediante webhooks. Está incluida en todos los planes, con los mismos límites para todos.
Todas las solicitudes van a https://api.letsrealty.io, envían y reciben JSON y llevan una clave de API.
1. Crea una clave de API
- Inicia sesión en tu consola de administración como administrador de la cuenta.
- Abre Integraciones → Claves de API y elige Crear clave.
- Ponle el nombre de la integración que la va a usar (el nombre aparece como "vía API: nombre" en todo lo que escriba) y elige sus permisos (scopes). Para enviar Leads, basta con
leads:ingest. - Copia la clave. Tiene la forma
lr_live_…y se muestra una sola vez; si la pierdes, revócala y crea otra.
Guarda la clave en un servidor. Cualquiera que la tenga puede actuar en nombre de tu agencia dentro de sus permisos.
2. Haz tu primera llamada
Envía un Lead con 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": "Formulario del sitio",
"type": "inquiry",
"person": { "name": "Ana Rojas", "email": "ana@example.com", "phone": "+506 8888 1234" },
"message": "¿Sigue disponible la casa en Escazú?"
}'
La respuesta es 201 Created con el Lead nuevo, o 200 OK si Ana ya era un Lead (se busca por email y luego por teléfono):
{
"lead": { "id": "6f1c…", "name": "Ana Rojas", "source": "api", "status": "new", "…": "…" },
"inquiry_id": "0b9e…",
"activity_id": null,
"warnings": []
}
El Lead ya aparece en tu pipeline con su consulta, recibe un responsable del Lead y notifica a tu equipo igual que una consulta desde el sitio web.
3. Léelo de vuelta
Con una clave que tenga leads:read:
curl https://api.letsrealty.io/v1/leads?limit=50 \
-H "Authorization: Bearer $LETSREALTY_API_KEY"
4. Lee y fija el nivel de un Lead
Cada Lead tiene dos niveles (hot, warm, moderate o cold):
score_tieres el de la IA, con suscorey suscore_reasoning. Esnullmientras el Lead está sin puntuar.tieres el nivel del Lead: el que un usuario fijó a mano si lo hay, y si noscore_tier. Ordena y filtra por este; la consola lo hace.
Mientras hay un nivel fijado, pinned_tier lo tiene, tier_pinned_by dice quién lo fijó (el nombre del usuario, o "via API: nombre de la clave") y tier_pinned_at cuándo. El Lead Score sigue actualizando score_tier por debajo y nunca cambia el nivel fijado.
Con leads:write, fija un nivel, o quítalo con 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"}'
Fijarlo o quitarlo envía lead.updated con pinned_tier en changed_fields. Funciona esté o no activada la puntuación de Leads.
5. Cierra un Lead como perdido, con el motivo
Mueve un Lead a closed_lost con un lost_reason: other_agency, on_their_own, price, financing, property_unavailable, not_ready, unreachable, not_a_lead, u other con un 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"}'
Aquí el motivo es opcional: un Lead cerrado sin él queda como not_given. Los Leads tienen lost_reason y lost_reason_note mientras están en closed_lost, y null en cualquier otro estado; sacar un Lead de closed_lost los borra. Un motivo enviado con otro estado se rechaza (422).
Siguientes pasos
- Autenticación y permisos — qué permite cada permiso.
- Ingesta de Leads — atribución, propiedades, agentes y cargas históricas.
- Webhooks — entérate cuando llega o cambia un Lead.
- Referencia de la API — todas las operaciones y campos. El archivo OpenAPI 3.1 completo está en /openapi.json.