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

  1. Inicia sesión en tu consola de administración como administrador de la cuenta.
  2. Abre Integraciones → Claves de API y elige Crear clave.
  3. 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.
  4. 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_tier es el de la IA, con su score y su score_reasoning. Es null mientras el Lead está sin puntuar.
  • tier es el nivel del Lead: el que un usuario fijó a mano si lo hay, y si no score_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