Saltar al contenido principal
El lead es el recurso central de FlowEstate. Cada endpoint en esta página opera dentro del tenant de la organización que llama — no puedes leer ni escribir leads de otra organización con la misma key.

​
Listar leads

GET /leads
Scope: leads:read

​
Query parameters

ParámetroTipoNotas
limit, offset, sortOrder, query—Ver Paginación. query matchea nombre, apellido, email, empresa y dígitos del teléfono.
sortBystringUno de createdAt, firstName, email, company, status, source, estimatedValue.
statusenumFiltrar por LeadStatus.
sourceenumFiltrar por LeadSource.

​
Response 200

{
  "data": [
    {
      "id": "lead_...",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "email": "ada@example.com",
      "phone": "+18095551234",
      "company": "Analytical Engines",
      "jobTitle": "CTO",
      "status": "new",
      "source": "website",
      "stageId": null,
      "stageName": null,
      "estimatedValue": null,
      "score": null,
      "temperature": null,
      "notes": null,
      "city": null,
      "state": null,
      "country": "DO",
      "projectId": null,
      "projectName": null,
      "unitId": null,
      "assignedToId": null,
      "assignedTo": null,
      "customFields": null,
      "createdAt": "2026-04-29T18:04:15.000Z",
      "updatedAt": "2026-04-29T18:04:15.000Z"
    }
  ],
  "pagination": { "total": 327, "limit": 50, "offset": 0, "hasMore": true }
}

​
Crear un lead

POST /leads
Scope: leads:write Al menos uno de email o phone es requerido. Las cadenas vacías cuentan como ausentes.

​
Request body

{
  "firstName": "Ada",
  "lastName": "Lovelace",
  "email": "ada@example.com",
  "phone": "+18095551234",
  "company": "Analytical Engines",
  "jobTitle": "CTO",
  "status": "new",
  "source": "meta",
  "stageId": "uuid-u-omitido",
  "estimatedValue": 250000,
  "score": 80,
  "temperature": "hot",
  "notes": "Vino de audiencia Lookalike",
  "city": "Punta Cana",
  "state": "La Altagracia",
  "country": "DO",
  "projectId": "uuid-u-omitido",
  "unitId": "uuid-u-omitido",
  "customFields": {
    "campaignName": "Q3-launch",
    "leadId": "2442330062872321"
  }
}
Semántica del campo source. FlowEstate acepta cualquier string como source. Los valores conocidos de LeadSource se guardan tal cual. Los desconocidos se guardan como other en la columna enum, con la cadena original preservada en sourceMetadata.providedSource. Esto te permite mantener tu propio mapeo de UTM/campaña sin perder datos.

​
Response 201

{
  "id": "lead_...",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "email": "ada@example.com",
  "phone": "+18095551234",
  "company": "Analytical Engines",
  "status": "new",
  "source": "meta",
  "createdAt": "2026-04-29T18:04:15.000Z",
  "updatedAt": "2026-04-29T18:04:15.000Z"
}

​
Errores comunes

  • 400 VALIDATION_ERROR — email inválido, o falta tanto email como teléfono.
  • 403 FORBIDDEN — límite del plan alcanzado. El mensaje identifica el límite.

​
Efectos secundarios de webhooks

Se dispara un evento lead.created con X-FlowEstate-Source: api.

​
Obtener un lead

GET /leads/{leadId}
Scope: leads:read. Devuelve la misma forma que un item de la lista. 404 NOT_FOUND si el lead no existe o pertenece a otra organización.

​
Actualizar un lead

PUT /leads/{leadId}
Scope: leads:write. Mismo body que crear, todos los campos opcionales. Debes proveer al menos un campo. La regla de identidad de contacto (email o teléfono) sigue aplicando tras el merge. Pasa null para limpiar un campo; omítelo para dejarlo intacto.

​
Efectos secundarios de webhooks

  • Siempre: lead.updated.
  • Si cambió stageId: lead.stage_changed.
  • Si cambió status a won: lead.won. A lost: lead.lost.
  • Si cambió assignedToId: lead.assigned (cuando se setea) o lead.unassigned (cuando se limpia).

​
Eliminar un lead

DELETE /leads/{leadId}
Scope: leads:write.

​
Response 200

{ "deleted": true, "id": "lead_..." }

​
Efectos secundarios de webhooks

Se dispara un evento lead.deleted.

​
Buscar un lead

GET /leads/search
Scope: leads:read. Diseñado para los pasos “Find Lead” de Zapier / Make.

​
Query parameters

Al menos uno de estos es requerido:
ParámetroDescripción
emailMatch exacto (normalizado a minúsculas).
phoneMatchea contra la forma solo-dígitos de los teléfonos guardados (así +1 (809) 555-1234 matchea 8095551234).
qMatch difuso sobre nombre/apellido, email, empresa.
limit1..50, default 10.

​
Response 200

{
  "data": [
    {
      "id": "lead_...",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "email": "ada@example.com",
      "phone": "+18095551234",
      "company": "Analytical Engines",
      "status": "new",
      "source": "website",
      "stageId": null,
      "stageName": null,
      "assignedTo": null,
      "createdAt": "2026-04-29T18:04:15.000Z"
    }
  ]
}

​
Listar actividades

GET /leads/{leadId}/activities
Scope: leads:read. Lista actividades del timeline (notas, llamadas, correos, reuniones, eventos del sistema).

​
Query parameters

ParámetroNotas
limit1..100, default 20.
offsetDefault 0.
typeFiltrar por LeadActivityType.
activityScopeFiltrar por LeadActivityScope. Default lead_event.

​
Response 200

{
  "data": [
    {
      "id": "act_...",
      "leadId": "lead_...",
      "type": "note",
      "activityScope": "lead_event",
      "content": "Llamé y dejé buzón de voz",
      "changes": null,
      "communicationType": null,
      "communicationDirection": null,
      "user": { "id": "user_...", "name": "...", "email": "...", "image": null },
      "createdAt": "2026-04-29T18:04:15.000Z"
    }
  ],
  "pagination": { "total": 12, "limit": 20, "offset": 0, "hasMore": false }
}

​
Agregar una nota

POST /leads/{leadId}/notes
Scope: leads:write.

​
Request body

{ "content": "Hablamos hoy, muy interesado" }
content es requerido, 1..5000 caracteres.

​
Response 201

{
  "id": "act_...",
  "leadId": "lead_...",
  "content": "Hablamos hoy, muy interesado",
  "createdAt": "2026-04-29T18:04:15.000Z"
}

​
Efectos secundarios de webhooks

Se dispara un evento lead.note_added.

​
Registrar una comunicación

POST /leads/{leadId}/communications
Scope: leads:write. Registra una llamada, correo, reunión o mensaje de redes sociales en el timeline del lead.

​
Request body

{
  "type": "call",
  "direction": "outbound",
  "content": "Conversamos sobre disponibilidad de unidades"
}
CampoRequeridoNotas
typesíUno de call, email, meeting, social_message.
directionsíinbound o outbound.
contentnoTexto libre, ≤ 5000 caracteres.

​
Response 201

{
  "id": "act_...",
  "leadId": "lead_...",
  "type": "call",
  "direction": "outbound",
  "content": "Conversamos sobre disponibilidad de unidades",
  "createdAt": "2026-04-29T18:04:15.000Z"
}

​
Efectos secundarios de webhooks

Se dispara un evento lead.communication_logged.