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.
Una credencial personal solo ve la cartera actual del caller (asignados, no deshabilitados). Listar, buscar, ficha, actividades, notas, comunicaciones, comercial y enriquecimiento usan ese filtro. Fuera de la cartera → 404 NOT_FOUND. Crear o eliminar leads no está disponible con una credencial personal.

Listar leads

Scope: leads:read

Query parameters

Response 200


Crear un lead

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

Request body

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.

Etapa del pipeline

stageId es opcional y se comporta en dos pasos:
  • Omitido — el lead cae en la etapa por defecto del pipeline de la organización. Nunca se crea sin etapa, así que siempre aparece en los reportes de funnel de la organización.
  • Provisto — la etapa tiene que pertenecer al pipeline de la organización que llama. Una etapa de otro tenant, o una que ya no existe, se rechaza con 400 VALIDATION_ERROR y no se crea ningún lead.
Esto es un cambio de comportamiento. Hasta esta versión, un POST /leads sin stageId creaba el lead sin etapa ninguna, y un stageId que no pertenecía a la organización se guardaba tal cual. Los leads creados así quedaban invisibles para el reporte de funnel. Los leads nuevos ya no pueden quedar así.
Los leads existentes no se tocan — esto aplica solo a la creación. Para mover un lead después, usá PUT /leads/{leadId}.

Deduplicación y fusión

Un lead se identifica por su identidad de contacto: el correo (en minúsculas) o el teléfono reducido a dígitos. Publicar un contacto que ya existe en tu organización no crea un segundo lead — la llamada fusiona sobre el que ya estaba y te lo devuelve.
Esto es un cambio de comportamiento. Hasta esta versión, publicar el mismo contacto dos veces dejaba dos leads. Un reintento de tu automatización, o el mismo formulario enviado dos veces, ya no duplican.
La fusión sólo rellena campos vacíos. Un campo que el lead ya trae nunca se pisa, así que lo que alguien cargó a mano siempre le gana a lo que llega después por la API. customFields se fusiona clave por clave: las claves que el lead no tiene se agregan, y las que ya tiene se dejan intactas — incluidas las que valen null o "". Tres campos no se fusionan nunca: status, stageId y firstWonAt. Dicen dónde está el lead en el embudo, y eso lo decide la organización, no quien publica. Para mover un lead usa PUT /leads/{leadId}. La respuesta te dice cuál de los dos casos ocurrió:
El código es 201 en los dos casos. Mirá outcome, y no el código de estado, para distinguirlos.
El match es por organización: el mismo correo en dos inquilinos distintos son dos personas distintas. Dos llamadas que compiten por el mismo contacto se serializan, así que la concurrencia tampoco puede producir un duplicado. Una fusión no consume cupo del plan, así que una organización en su tope de leads igual puede enriquecer los que ya tiene.

Distribución por round robin

POST /leads ejecuta el round robin de punta a punta en una sola llamada: crea el lead, lo asigna a través de la rotación de un pool y emite lead.assigned para que tu automatización downstream (por ejemplo, una notificación de WhatsApp al agente) se dispare. No hace falta el webhook universal de leads ni un bridge intermedio. Cuando el lead no tiene responsable, la asignación se resuelve en este orden:
  1. assignedToId — se asigna directamente a ese miembro.
  2. roundRobinId — se asigna a través de ese pool. Como el destino es explícito, se respeta aunque el pool no tenga conexiones, y se omiten los flags assignInboundLeads / assignManualLeads del pool.
  3. Ninguno — asignación automática genérica: el lead se enruta a un pool activo con assignInboundLeads habilitado. Un pool sin conexiones funciona como el pool “inbound genérico” comodín, así que puedes distribuir leads de la API sin configurar ninguna conexión de webhook.
Si ningún pool coincide —o el pool encontrado no tiene participante elegible— el lead se crea sin asignar. La asignación es best-effort: nunca falla la creación del lead. Esto también corre en una fusión. Si la llamada cayó sobre un lead que todavía no tenía responsable, el round robin igual lo asigna — así que una publicación repetida puede ser lo que finalmente enrute un lead que había entrado sin asignar.

Response 201

assignedToId es el miembro asignado (o null si el lead quedó sin asignar). roundRobinId es el pool a través del cual se asignó el lead (null para un assignedToId explícito o cuando no hubo asignación). assignment vale assigned-now cuando fue esta llamada la que asignó, pre-existing cuando el lead ya tenía responsable, y none cuando no se asignó a nadie.
La misma llamada para un contacto que ya existía, sobre un lead que no tenía empresa ni cargo cargados:

Errores comunes

  • 400 VALIDATION_ERROR — email inválido, falta tanto email como teléfono, assignedToId no es miembro de esta organización, o stageId no pertenece a esta organización. Todo se valida antes de crear el lead.
  • 403 PLAN_LIMIT_REACHED — la organización está en su tope de leads. Una fusión nunca se frena por esto: no se crea ningún lead, así que no consume cupo. No reintentes — el veredicto no cambia hasta que se mejore el plan. Ver Errores de límite del plan.

Efectos secundarios de webhooks

  • Al crear: lead.created (con X-FlowEstate-Source: api).
  • Al fusionar: no sale lead.created — no se creó nada. Tampoco sale un lead.updated por el enriquecimiento.
  • Si esta llamada asigna el lead (vía assignedToId, roundRobinId, o asignación automática genérica): lead.assigned. También sale en una fusión, cuando el lead sobre el que cayó todavía no tenía responsable. Su flag autoAssigned es true cuando el round robin eligió al participante, y false para un assignedToId explícito — para distinguir ambos casos downstream.
O sea que una publicación repetida dispara o nada, o lead.assigned, nunca lead.created. Reconciliá con el outcome de tu propia llamada y no con los eventos.

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

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:

Response 200


Listar actividades

Scope: leads:read. Lista actividades del timeline (notas, llamadas, correos, reuniones, eventos del sistema).

Query parameters

Response 200


Agregar una nota

Scope: leads:write.

Request body

content es requerido, 1..5000 caracteres.

Response 201

Efectos secundarios de webhooks

Se dispara un evento lead.note_added.

Registrar una comunicación

Scope: leads:write. Registra una llamada, correo, reunión o mensaje de redes sociales en el timeline del lead.

Request body

Response 201

Efectos secundarios de webhooks

Se dispara un evento lead.communication_logged.

Actualizar seguimiento comercial

Scope: leads:write. Actualiza solo campos de pipeline/comercial. No cambia asignación, fuente, consentimientos ni customFields.

Request body

Se requiere al menos un campo.

Response 200

Errores comunes

  • 400 INVALID_STAGE — stageId no es una etapa de esta organización.
  • 409 FOLLOW_UP_ACTIVE — hay un seguimiento activo; complétalo o límpialo antes.
  • 404 NOT_FOUND — el lead no existe o está fuera de la cartera del caller.

Enriquecer un lead

Scope: leads:write. Por defecto completa campos de contacto vacíos. Para sobrescribir un valor guardado, inclúyelo en correct con el expected actual.

Request body

Response 200

skipped lista los campos enviados que no estaban vacíos ni se corrigieron.

Errores comunes

  • 409 STALE_CORRECTION — expected ya no coincide; vuelve a leer el lead y reintenta.
  • 409 IDENTITY_CONFLICT — el email o teléfono ya pertenecen a otro lead. Esa otra ficha no se devuelve.
  • 404 NOT_FOUND — el lead no existe o está fuera de la cartera del caller.