Documentation Index
Fetch the complete documentation index at: https://developers.flowestate.app/llms.txt
Use this file to discover all available pages before exploring further.
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
Scope: leads:read
Query parameters
| Parámetro | Tipo | Notas |
|---|
limit, offset, sortOrder, query | — | Ver Paginación. query matchea nombre, apellido, email, empresa y dígitos del teléfono. |
sortBy | string | Uno de createdAt, firstName, email, company, status, source, estimatedValue. |
status | enum | Filtrar por LeadStatus. |
source | enum | Filtrar 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
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
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
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
Scope: leads:write.
Response 200
{ "deleted": true, "id": "lead_..." }
Efectos secundarios de webhooks
Se dispara un evento lead.deleted.
Buscar un lead
Scope: leads:read. Diseñado para los pasos “Find Lead” de Zapier / Make.
Query parameters
Al menos uno de estos es requerido:
| Parámetro | Descripción |
|---|
email | Match exacto (normalizado a minúsculas). |
phone | Matchea contra la forma solo-dígitos de los teléfonos guardados (así +1 (809) 555-1234 matchea 8095551234). |
q | Match difuso sobre nombre/apellido, email, empresa. |
limit | 1..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
leads:read. Lista actividades del timeline (notas, llamadas, correos, reuniones, eventos del sistema).
Query parameters
| Parámetro | Notas |
|---|
limit | 1..100, default 20. |
offset | Default 0. |
type | Filtrar por LeadActivityType. |
activityScope | Filtrar 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
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
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"
}
| Campo | Requerido | Notas |
|---|
type | sí | Uno de call, email, meeting, social_message. |
direction | sí | inbound o outbound. |
content | no | Texto 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.
