Leads por API

Última actualización: 2026-10-035 min de lectura

Esta sección da acceso programático a sus propios leads del CRM: un sitio web o un formulario externo puede enviar solicitudes directamente al panel, y su sistema puede leerlas y moverlas por los estados.

Dirección base: https://developers.grem.capital/api/v1.

Los leads son privados. A diferencia del catálogo público de inmuebles, sin el ámbito adecuado no hay acceso: leer requiere leads:read, modificar requiere leads:write. Solo ve los leads en los que usted es remitente o destinatario. Las solicitudes no se cobran.

Lista

GET /leads?status=new&type=buy&priority=hot&page=1&limit=20
Authorization: Bearer gsk_live_...

Filtros: status, type, priority, source, role, archived, pool, from, to, page, limit, sort. Los leads archivados no están en la lista normal: añada archived=true. pool=true (solo claves de agencia): los leads del pool común de la agencia; una clave personal lo ignora.

limit (1-50, 20 por defecto) y page (desde 1) fuera del rango se ajustan a él, no se rechazan. Otros valores no válidos de un parámetro conocido (un valor de enumeración desconocido, un page no entero, una fecha no válida en from o to) se rechazan con 400 validation indicando el campo.

Un lead

GET /leads/{id}?expand=history,documents

expand añade el historial de estados y acciones (history) y los documentos adjuntos (documents).

Forma de un lead

id, status, type, priority, source, tags, isArchived; type: buy, rent, viewing, sell, contract, transfer o user
createdAt, updatedAt, lastActivityAt
customer: nombre, país, mensajero y un bloque contact (phone, email, messengerHandle, profileUrl)
budget: { value, currency }
intent: ciudad, distritos, tipo de operación e intención del cliente
comments: el comentario del cliente y el suyo, por separado
object: el inmueble al que se refiere la solicitud
agency: solo en leads de agencia, el id de la agencia y si el lead está en el pool común

Nunca se devuelven contactos de otros agentes, puntuaciones internas ni indicadores de servicio.

Enviar una solicitud

curl -X POST https://developers.grem.capital/api/v1/leads \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: form-2026-09-07-0001" \
  -d '{
    "customer": {
      "name": "Olena Kovalchuk",
      "country": "UA",
      "contact": { "phone": "+380971234567", "email": "[email protected]" }
    },
    "type": "buy",
    "budget": { "value": 120000, "currency": "USD" },
    "intent": { "targetCity": "Kyiv", "leadIntent": "buyer" },
    "comments": "Busca un piso de 2 habitaciones cerca del metro",
    "priority": "warm",
    "consent": true
  }'

Obligatorios: customer.name y al menos una forma de contactar al cliente en customer.contact. type: buy (por defecto) o rent. priority: hot, warm o cold. Añada objectId si la solicitud se refiere a un inmueble concreto, y hasta diez tags propias.

Idempotency-Key le protege de duplicados: si su formulario repite la solicitud tras un tiempo de espera, el lead no se crea dos veces. Vea Idempotencia.

pool: true envía la solicitud al pool común de reparto en lugar de a su CRM. Por defecto el lead le llega a usted.

Cada lead creado por API aparece en el panel con la fuente «API», para que pueda distinguirlo.

Modificar un lead

PATCH /leads/{id}
{ "status": "in progress", "priority": "hot", "tags": ["mortgage"], "brokerComments": "..." }

Puede cambiar el estado, la prioridad, las etiquetas y su propio comentario. Basta con un campo. Estados: new, in progress, processing, agreement, closed, not target, failed. Se aplican las reglas del panel: un lead con inmueble se cierra con la finalización en el panel (code: finalize), un lead que espera la comisión mantiene su estado (fee_pending), un trato cerrado con contrato solo cambia en el panel (closed): 422 con el motivo en code. Otros motivos: sender (usted pasó el lead: lo gestiona el destinatario), module (un lead de Swipe Match, su estado lo lleva el módulo), agreement, network_readonly, forbidden.

Retirar un lead

DELETE /leads/{id}

El lead se archiva en lugar de eliminarse: sale de la lista normal, pero sigue disponible con ?archived=true. Un lead con contrato vigente o acuerdo de finalización, un lead cerrado con inmueble sin finalizar y un lead que espera la comisión no se archivan: 422 con code contract_active, agreement, finalize o fee_pending.

Inmuebles para un lead

GET /leads/{id}/matches?page=1&limit=20

Devuelve inmuebles que encajan con la solicitud del cliente: el tipo, la ciudad y el presupuesto salen del propio lead o del inmueble vinculado. Gratis.

Pool de la agencia

Las claves de agencia tienen dos acciones de pool:

POST /leads/{id}/claim               tomar un lead del pool
POST /leads/{id}/claim?assignTo=...  asignarlo a un miembro del equipo
POST /leads/{id}/return-to-pool      devolver un lead al pool

Tomar: por defecto el lead va al propietario de la agencia; assignTo (id del miembro) lo pueden pasar el propietario o un gestor.
Devolver al pool: de gestor hacia arriba, o el agente al que está asignado el lead. Cuerpo opcional: {"reason": "..."}. Un lead que archivaron las reglas del pool: 422 con code: pool_archived; restáurelo primero en el panel.
Una clave personal o un rol insuficiente, 403 con title: forbidden; tomar un lead que ya no está en el pool, 404.
Ambas acciones envían un evento lead.updated.

Seguimiento de cambios

En lugar de consultar la lista, suscríbase a lead.created y lead.updated: vea Webhooks. El evento no lleva datos personales: solo indica qué lead cambió; la ficha se lee con una solicitud aparte.