Leads por la API

Última actualización: 2026-09-074 min de lectura

Esta sección da acceso programático a sus propios leads del CRM: una web o un formulario externo pueden enviar consultas directamente al gabinete, 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 objetos, aquí no hay acceso sin alcance: leer exige leads:read y modificar exige leads:write. Solo ve los leads en los que usted es el emisor o el receptor.

El listado

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

Parámetros de filtro: status, type, priority, source, role, archived, pool, from, to, page, limit, sort. Los leads archivados quedan fuera del listado normal: añada archived=true.

Un lead

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

expand añade la crónica de estados y acciones (history) y la lista de documentos adjuntos (documents).

La forma del lead

id, status, type, priority, source, tags, isArchived
createdAt, updatedAt, lastActivityAt
customer: nombre, país, mensajería y un bloque contact (phone, email, messengerHandle, profileUrl)
budget: { value, currency }
intent: ciudad, distritos, tipo de operación y qué busca el cliente
comments: el comentario del cliente y el suyo, por separado
object: el anuncio al que se refiere la consulta
deadline, reminder
agency: presente solo en leads de agencia: el id de la agencia y si el lead está en el fondo común

Nunca se devuelven los contactos de otros brókers, la puntuación interna ni las marcas de servicio.

Enviar una consulta desde fuera

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": "olena@example.com" }
    },
    "type": "buy",
    "budget": { "value": 120000, "currency": "USD" },
    "intent": { "targetCity": "Kyiv", "leadIntent": "buyer" },
    "comments": "Looking for a two-room flat near the metro",
    "priority": "warm",
    "consent": true
  }'

Obligatorio: customer.name y al menos una forma de contacto en customer.contact. type es buy (por defecto) o rent. priority es hot, warm o cold. Puede añadir un objectId cuando la consulta trata de un anuncio concreto, y hasta diez etiquetas propias en tags.

La cabecera Idempotency-Key le libra de duplicados: si su formulario reintentó tras un tiempo de espera, el lead no se crea dos veces. Véase Idempotencia.

La marca pool: true dirige la consulta al fondo común para su reparto en vez de a su propio CRM. Por defecto, el lead cae en su cuenta.

Todo lead creado por la API lleva en el gabinete la fuente «API», así que se distingue del resto.

Cambiar un lead

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

Se pueden cambiar el estado, la prioridad, las etiquetas y su propio comentario. Basta con un campo. Estados disponibles: new, in progress, processing, agreement, closed, not target, failed.

Apartar un lead

DELETE /leads/{id}

Esto archiva, no borra: el lead sale del listado normal pero sigue accesible con ?archived=true.

Inmuebles que encajan con un lead

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

Devuelve anuncios que responden a la petición del cliente: el tipo, la ciudad y el presupuesto salen del propio lead o del anuncio asociado. La llamada es gratis.

El fondo de la agencia

Las claves de agencia disponen de dos acciones sobre el fondo:

POST /leads/{id}/claim               tomar para sí un lead del fondo
POST /leads/{id}/claim?assignTo=…    asignar el lead a un miembro del equipo
POST /leads/{id}/return-to-pool      devolver el lead al fondo

Ambas exigen un rol en la agencia que permita repartir leads. Una clave personal se rechaza, y tomar un lead que ya cogió otra persona devuelve 409.

Seguir los cambios

En vez de consultar el listado, suscríbase a los eventos lead.created y lead.updated: véase Webhooks. El evento en sí no lleva datos personales: solo dice qué lead ha cambiado, y la ficha se lee en una petición aparte.