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
leads:read
Query parameters
Response 200
Crear un lead
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_ERRORy no se crea ningún lead.
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. 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 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:
assignedToId— se asigna directamente a ese miembro.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 flagsassignInboundLeads/assignManualLeadsdel pool.- Ninguno — asignación automática genérica: el lead se enruta a un pool activo con
assignInboundLeadshabilitado. 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.
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.
Errores comunes
400 VALIDATION_ERROR— email inválido, falta tanto email como teléfono,assignedToIdno es miembro de esta organización, ostageIdno 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(conX-FlowEstate-Source: api). - Al fusionar: no sale
lead.created— no se creó nada. Tampoco sale unlead.updatedpor 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 flagautoAssignedestruecuando el round robin eligió al participante, yfalsepara unassignedToIdexplícito — para distinguir ambos casos downstream.
lead.assigned, nunca lead.created. Reconciliá con el outcome de tu propia llamada y no con los eventos.
Obtener un lead
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
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ó
statusawon:lead.won. Alost:lead.lost. - Si cambió
assignedToId:lead.assigned(cuando se setea) olead.unassigned(cuando se limpia).
Eliminar un lead
leads:write.
Response 200
Efectos secundarios de webhooks
Se dispara un eventolead.deleted.
Buscar un lead
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
leads:read. Lista actividades del timeline (notas, llamadas, correos, reuniones, eventos del sistema).
Query parameters
Response 200
Agregar una nota
leads:write.
Request body
content es requerido, 1..5000 caracteres.
Response 201
Efectos secundarios de webhooks
Se dispara un eventolead.note_added.
Registrar una comunicación
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 eventolead.communication_logged.
Actualizar seguimiento comercial
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—stageIdno 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
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—expectedya 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.