> For the complete documentation index, see [llms.txt](https://prometheo.gitbook.io/prometheo-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://prometheo.gitbook.io/prometheo-api/leads.md).

# Leads

## Obtener lista paginada de leads

> Retorna una lista paginada de leads con filtros opcionales. Los leads se ordenan por fecha de creación descendente.\
> Los tags aceptan lógica OR (default) o AND. También se pueden combinar \`tags\_any\` y \`tags\_all\` en la misma request.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Leads"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"LeadListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"leads":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Página actual"},"limit":{"type":"integer","description":"Leads por página"},"total":{"type":"integer","description":"Total de leads"},"total_pages":{"type":"integer","description":"Total de páginas"}}}}},"Lead":{"type":"object","description":"Representación de un lead/contacto","properties":{"id":{"type":"string","description":"ID único del lead"},"contact_id":{"type":"string","description":"Identificador del contacto (teléfono, username, etc)"},"connection_type":{"type":"string","description":"Tipo de conexión del lead","enum":["whatsapp-business","whatsapp-lite","whatsapp-hybrid","instagram","facebook","email","tiktok","mercado-libre"]},"phone_number":{"type":"string","nullable":true,"description":"Número de teléfono"},"email":{"type":"string","nullable":true,"description":"Email del lead"},"first_name":{"type":"string","nullable":true,"description":"Nombre del lead"},"last_name":{"type":"string","nullable":true,"description":"Apellido del lead"},"comments":{"type":"string","nullable":true,"description":"Comentarios sobre el lead"},"summary":{"type":"string","nullable":true,"description":"Resumen generado de la conversación"},"instagram_username":{"type":"string","nullable":true,"description":"Username de Instagram (si aplica)"},"variables":{"type":"object","description":"Variables personalizadas del lead","additionalProperties":{"type":"string"}},"smart_tags":{"type":"array","description":"Smart tags asignados al lead","items":{"$ref":"#/components/schemas/SmartTag"}},"moderator":{"$ref":"#/components/schemas/LeadModerator"},"ads":{"type":"array","description":"Anuncios de origen del lead (Meta/Instagram). Vacío si el contacto no proviene de un anuncio. Un objeto por ad_id único. Cada anuncio puede incluir el ctwa_clid del click más reciente a ese ad.","items":{"$ref":"#/components/schemas/LeadAd"}},"ctwa_clid":{"type":"string","nullable":true,"description":"Click ID de Click-to-WhatsApp (CTWA) más reciente del lead. `null` si el contacto no proviene de un anuncio de WhatsApp. Sirve para enviar conversiones a Meta (CAPI)."},"created_at":{"type":"string","format":"date-time","description":"Fecha de creación"},"updated_at":{"type":"string","format":"date-time","description":"Fecha de última actualización"},"last_message_at":{"type":"string","format":"date-time","nullable":true,"description":"Fecha del último mensaje"}}},"SmartTag":{"type":"object","description":"Smart tag asignado a un lead","properties":{"id":{"type":"string","description":"ID del smart tag"},"name":{"type":"string","description":"Nombre del smart tag"}}},"LeadModerator":{"type":"object","nullable":true,"description":"Moderador asignado al lead. `null` si no tiene uno.","properties":{"id":{"type":"string","description":"ID del usuario moderador"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}}},"LeadAd":{"type":"object","description":"Anuncio de origen asociado a un lead","properties":{"ad_id":{"type":"string","description":"ID del anuncio (source_id o ad_id de Meta)"},"ad":{"type":"string","nullable":true,"description":"Texto/body del anuncio"},"ctwa_clid":{"type":"string","nullable":true,"description":"Click ID de Click-to-WhatsApp asociado a este anuncio. `null` en referrals de Instagram u otros canales sin CTWA."}}},"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}},"paths":{"/leads":{"get":{"tags":["Leads"],"summary":"Obtener lista paginada de leads","description":"Retorna una lista paginada de leads con filtros opcionales. Los leads se ordenan por fecha de creación descendente.\nLos tags aceptan lógica OR (default) o AND. También se pueden combinar `tags_any` y `tags_all` en la misma request.","parameters":[{"name":"page","in":"query","description":"Número de página (comienza en 1)","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","description":"Cantidad de leads por página (máximo 100)","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}},{"name":"connection_type","in":"query","description":"Filtrar por tipo de conexión","schema":{"type":"string","enum":["whatsapp-business","whatsapp-lite","whatsapp-hybrid","instagram","facebook","email","tiktok","mercado-libre"]}},{"name":"tags","in":"query","description":"IDs de smart tags separados por coma. Por defecto el lead debe tener AL MENOS UNO (OR). Usar `tags_operator=and` para exigir TODOS los tags.","schema":{"type":"string"}},{"name":"tags_operator","in":"query","description":"Operador aplicado a `tags`. `or` (default) = el lead tiene cualquiera de los tags. `and` = el lead tiene todos los tags. Alias aceptados: `any`/`all`. También se puede enviar como `tags_match`.","schema":{"type":"string","enum":["or","and"],"default":"or"}},{"name":"tags_any","in":"query","description":"IDs de smart tags separados por coma. El lead debe tener AL MENOS UNO (OR). Se puede combinar con `tags_all`.","schema":{"type":"string"}},{"name":"tags_all","in":"query","description":"IDs de smart tags separados por coma. El lead debe tener TODOS (AND). Se puede combinar con `tags_any`.","schema":{"type":"string"}},{"name":"moderator","in":"query","description":"Filtrar por moderador asignado. IDs de usuario separados por coma, o `unassigned` para leads sin moderador. Alias: `moderators`.","schema":{"type":"string"}},{"name":"unassigned","in":"query","description":"Si es `true`, incluye leads sin moderador asignado","schema":{"type":"boolean"}},{"name":"search","in":"query","description":"Búsqueda por nombre, email, teléfono o username de Instagram","schema":{"type":"string"}},{"name":"start_date","in":"query","description":"Filtrar leads creados desde esta fecha (ISO 8601)","schema":{"type":"string","format":"date-time"}},{"name":"end_date","in":"query","description":"Filtrar leads creados hasta esta fecha (ISO 8601)","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Lista de leads obtenida exitosamente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadListResponse"}}}},"400":{"description":"Error de validación (connection_type, tags o moderator inválidos)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"No autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```

## Crear un lead

> Crea un nuevo lead usando el mismo proceso que la creación manual desde la plataforma: el teléfono se normaliza a formato E.164, se rechazan duplicados por teléfono y canal, se crea la conversación asociada y se disparan las automatizaciones configuradas para el evento de creación de lead. Si no se envía connection\_type, se detecta automáticamente la conexión de WhatsApp activa de la organización (prioridad: whatsapp-business, luego whatsapp-hybrid, whatsapp-lite y otras variantes de WhatsApp). Las variables inválidas no abortan la creación y se informan en rejected\_fields. Los smart\_tags deben ser IDs de smart tags existentes de la organización.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Leads"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"LeadCreateRequest":{"type":"object","description":"Datos para crear un nuevo lead. El teléfono se normaliza a E.164 y se usa para generar el identificador del contacto según el canal. Si no se envía connection_type, se auto-detecta la conexión de WhatsApp activa de la organización.","required":["first_name","phone_number"],"properties":{"first_name":{"type":"string","description":"Nombre del lead"},"last_name":{"type":"string","description":"Apellido del lead"},"email":{"type":"string","description":"Email del lead"},"phone_number":{"type":"string","description":"Teléfono del lead. Debe contener solo dígitos (6-15 caracteres), opcionalmente con un + inicial. Se normaliza a formato E.164."},"connection_type":{"type":"string","description":"Canal de WhatsApp donde crear el lead. Si se omite, se detecta automáticamente la conexión de WhatsApp activa de la organización.","enum":["whatsapp-business","whatsapp-lite","whatsapp-hybrid"]},"variables":{"type":"object","description":"Variables personalizadas iniciales. Se valida que cada variable exista para la organización y que el valor sea del tipo correcto. Las variables inválidas no abortan la creación y se informan en rejected_fields.","additionalProperties":true},"smart_tags":{"type":"array","description":"IDs de smart tags a asignar al lead. Deben corresponder a smart tags existentes de la organización.","items":{"type":"string","description":"Id de la etiqueta."}}}},"LeadCreateResponse":{"type":"object","properties":{"success":{"type":"boolean"},"lead":{"$ref":"#/components/schemas/Lead"},"rejected_fields":{"type":"array","description":"Variables que no pudieron ser asignadas","items":{"type":"object","properties":{"field":{"type":"string","description":"Nombre del campo rechazado"},"reason":{"type":"string","description":"Motivo del rechazo"}}}}}},"Lead":{"type":"object","description":"Representación de un lead/contacto","properties":{"id":{"type":"string","description":"ID único del lead"},"contact_id":{"type":"string","description":"Identificador del contacto (teléfono, username, etc)"},"connection_type":{"type":"string","description":"Tipo de conexión del lead","enum":["whatsapp-business","whatsapp-lite","whatsapp-hybrid","instagram","facebook","email","tiktok","mercado-libre"]},"phone_number":{"type":"string","nullable":true,"description":"Número de teléfono"},"email":{"type":"string","nullable":true,"description":"Email del lead"},"first_name":{"type":"string","nullable":true,"description":"Nombre del lead"},"last_name":{"type":"string","nullable":true,"description":"Apellido del lead"},"comments":{"type":"string","nullable":true,"description":"Comentarios sobre el lead"},"summary":{"type":"string","nullable":true,"description":"Resumen generado de la conversación"},"instagram_username":{"type":"string","nullable":true,"description":"Username de Instagram (si aplica)"},"variables":{"type":"object","description":"Variables personalizadas del lead","additionalProperties":{"type":"string"}},"smart_tags":{"type":"array","description":"Smart tags asignados al lead","items":{"$ref":"#/components/schemas/SmartTag"}},"moderator":{"$ref":"#/components/schemas/LeadModerator"},"ads":{"type":"array","description":"Anuncios de origen del lead (Meta/Instagram). Vacío si el contacto no proviene de un anuncio. Un objeto por ad_id único. Cada anuncio puede incluir el ctwa_clid del click más reciente a ese ad.","items":{"$ref":"#/components/schemas/LeadAd"}},"ctwa_clid":{"type":"string","nullable":true,"description":"Click ID de Click-to-WhatsApp (CTWA) más reciente del lead. `null` si el contacto no proviene de un anuncio de WhatsApp. Sirve para enviar conversiones a Meta (CAPI)."},"created_at":{"type":"string","format":"date-time","description":"Fecha de creación"},"updated_at":{"type":"string","format":"date-time","description":"Fecha de última actualización"},"last_message_at":{"type":"string","format":"date-time","nullable":true,"description":"Fecha del último mensaje"}}},"SmartTag":{"type":"object","description":"Smart tag asignado a un lead","properties":{"id":{"type":"string","description":"ID del smart tag"},"name":{"type":"string","description":"Nombre del smart tag"}}},"LeadModerator":{"type":"object","nullable":true,"description":"Moderador asignado al lead. `null` si no tiene uno.","properties":{"id":{"type":"string","description":"ID del usuario moderador"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}}},"LeadAd":{"type":"object","description":"Anuncio de origen asociado a un lead","properties":{"ad_id":{"type":"string","description":"ID del anuncio (source_id o ad_id de Meta)"},"ad":{"type":"string","nullable":true,"description":"Texto/body del anuncio"},"ctwa_clid":{"type":"string","nullable":true,"description":"Click ID de Click-to-WhatsApp asociado a este anuncio. `null` en referrals de Instagram u otros canales sin CTWA."}}},"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}},"paths":{"/leads":{"post":{"tags":["Leads"],"summary":"Crear un lead","description":"Crea un nuevo lead usando el mismo proceso que la creación manual desde la plataforma: el teléfono se normaliza a formato E.164, se rechazan duplicados por teléfono y canal, se crea la conversación asociada y se disparan las automatizaciones configuradas para el evento de creación de lead. Si no se envía connection_type, se detecta automáticamente la conexión de WhatsApp activa de la organización (prioridad: whatsapp-business, luego whatsapp-hybrid, whatsapp-lite y otras variantes de WhatsApp). Las variables inválidas no abortan la creación y se informan en rejected_fields. Los smart_tags deben ser IDs de smart tags existentes de la organización.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadCreateRequest"}}}},"responses":{"201":{"description":"Lead creado exitosamente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadCreateResponse"}}}},"400":{"description":"Error de validación (first_name o phone_number faltantes, teléfono inválido, connection_type inválido, smart tags inexistentes o sin conexión de WhatsApp activa)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"No autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Ya existe un lead con ese teléfono en el canal indicado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```

## Obtener lead por ID

> Obtiene un contacto por su id.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Leads"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"LeadResponse":{"type":"object","properties":{"success":{"type":"boolean"},"lead":{"$ref":"#/components/schemas/Lead"}}},"Lead":{"type":"object","description":"Representación de un lead/contacto","properties":{"id":{"type":"string","description":"ID único del lead"},"contact_id":{"type":"string","description":"Identificador del contacto (teléfono, username, etc)"},"connection_type":{"type":"string","description":"Tipo de conexión del lead","enum":["whatsapp-business","whatsapp-lite","whatsapp-hybrid","instagram","facebook","email","tiktok","mercado-libre"]},"phone_number":{"type":"string","nullable":true,"description":"Número de teléfono"},"email":{"type":"string","nullable":true,"description":"Email del lead"},"first_name":{"type":"string","nullable":true,"description":"Nombre del lead"},"last_name":{"type":"string","nullable":true,"description":"Apellido del lead"},"comments":{"type":"string","nullable":true,"description":"Comentarios sobre el lead"},"summary":{"type":"string","nullable":true,"description":"Resumen generado de la conversación"},"instagram_username":{"type":"string","nullable":true,"description":"Username de Instagram (si aplica)"},"variables":{"type":"object","description":"Variables personalizadas del lead","additionalProperties":{"type":"string"}},"smart_tags":{"type":"array","description":"Smart tags asignados al lead","items":{"$ref":"#/components/schemas/SmartTag"}},"moderator":{"$ref":"#/components/schemas/LeadModerator"},"ads":{"type":"array","description":"Anuncios de origen del lead (Meta/Instagram). Vacío si el contacto no proviene de un anuncio. Un objeto por ad_id único. Cada anuncio puede incluir el ctwa_clid del click más reciente a ese ad.","items":{"$ref":"#/components/schemas/LeadAd"}},"ctwa_clid":{"type":"string","nullable":true,"description":"Click ID de Click-to-WhatsApp (CTWA) más reciente del lead. `null` si el contacto no proviene de un anuncio de WhatsApp. Sirve para enviar conversiones a Meta (CAPI)."},"created_at":{"type":"string","format":"date-time","description":"Fecha de creación"},"updated_at":{"type":"string","format":"date-time","description":"Fecha de última actualización"},"last_message_at":{"type":"string","format":"date-time","nullable":true,"description":"Fecha del último mensaje"}}},"SmartTag":{"type":"object","description":"Smart tag asignado a un lead","properties":{"id":{"type":"string","description":"ID del smart tag"},"name":{"type":"string","description":"Nombre del smart tag"}}},"LeadModerator":{"type":"object","nullable":true,"description":"Moderador asignado al lead. `null` si no tiene uno.","properties":{"id":{"type":"string","description":"ID del usuario moderador"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}}},"LeadAd":{"type":"object","description":"Anuncio de origen asociado a un lead","properties":{"ad_id":{"type":"string","description":"ID del anuncio (source_id o ad_id de Meta)"},"ad":{"type":"string","nullable":true,"description":"Texto/body del anuncio"},"ctwa_clid":{"type":"string","nullable":true,"description":"Click ID de Click-to-WhatsApp asociado a este anuncio. `null` en referrals de Instagram u otros canales sin CTWA."}}},"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}},"paths":{"/leads/{id}":{"get":{"tags":["Leads"],"summary":"Obtener lead por ID","description":"Obtiene un contacto por su id.","parameters":[{"name":"id","in":"path","required":true,"description":"Id del contacto.","schema":{"type":"string"}}],"responses":{"200":{"description":"Lead obtenido exitosamente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadResponse"}}}},"400":{"description":"ID inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"No autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Lead no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```

## Actualizar un lead

> Actualiza campos de un lead. Campos permitidos: email, first\_name, last\_name, comments, variables, phone\_number y smart\_tags. El campo phone\_number solo puede ser actualizado si el tipo de conexión NO es whatsapp-business, whatsapp-lite o whatsapp-hybrid. Las variables son validadas: deben existir previamente en la organización y el valor debe coincidir con el tipo definido. Las smart tags se actualizan mediante una operación explícita: add, replace o remove.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Leads"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"LeadUpdateRequest":{"type":"object","description":"Campos permitidos para actualizar un lead. El campo phone_number solo puede actualizarse si el lead NO es de tipo whatsapp-business, whatsapp-lite o whatsapp-hybrid. Las variables son validadas: deben existir previamente en la organización y el valor debe coincidir con el tipo definido (text, number, date, link,  price, enum). Para enum, el valor debe ser una opción válida. Las smart tags se actualizan con una operación explícita add, replace o remove.","properties":{"email":{"type":"string","description":"Email del lead"},"first_name":{"type":"string","description":"Nombre del lead"},"last_name":{"type":"string","description":"Apellido del lead"},"comments":{"type":"string","description":"Comentarios sobre el lead"},"phone_number":{"type":"string","description":"Teléfono (solo editable si NO es WhatsApp). Debe contener solo dígitos (6-15 caracteres)."},"variables":{"type":"object","description":"Variables personalizadas a actualizar. Se valida que cada variable exista para la organización y que el valor sea del tipo correcto (text, text_large,  number, date, link, price, enum). Para enum, el valor debe ser una de las  opciones válidas. Variables inválidas aparecerán en rejected_fields.","additionalProperties":true},"smart_tags":{"$ref":"#/components/schemas/SmartTagsUpdateOperation"}}},"SmartTagsUpdateOperation":{"type":"object","description":"Operación para modificar las smart tags asignadas al lead. Los IDs deben corresponder a smart tags existentes de la misma organización. El modo replace con ids vacío limpia todas las smart tags del lead. Si el resultado contiene más de un smart tag del mismo `exclusive_group`, se conserva únicamente el último agregado (el que se está asignando en esta operación) y se descartan los demás del grupo.","required":["mode","ids"],"properties":{"mode":{"type":"string","enum":["add","replace","remove"],"description":"add agrega las smart tags indicadas sin duplicar, replace reemplaza completamente la lista actual, remove quita solo las indicadas."},"ids":{"type":"array","description":"IDs de smart tags a agregar, reemplazar o quitar.","items":{"type":"string","description":"Id de la etiqueta."}}}},"LeadUpdateResponse":{"type":"object","properties":{"success":{"type":"boolean"},"lead":{"$ref":"#/components/schemas/Lead"},"rejected_fields":{"type":"array","description":"Campos que no pudieron ser actualizados","items":{"type":"object","properties":{"field":{"type":"string","description":"Nombre del campo rechazado"},"reason":{"type":"string","description":"Motivo del rechazo"}}}}}},"Lead":{"type":"object","description":"Representación de un lead/contacto","properties":{"id":{"type":"string","description":"ID único del lead"},"contact_id":{"type":"string","description":"Identificador del contacto (teléfono, username, etc)"},"connection_type":{"type":"string","description":"Tipo de conexión del lead","enum":["whatsapp-business","whatsapp-lite","whatsapp-hybrid","instagram","facebook","email","tiktok","mercado-libre"]},"phone_number":{"type":"string","nullable":true,"description":"Número de teléfono"},"email":{"type":"string","nullable":true,"description":"Email del lead"},"first_name":{"type":"string","nullable":true,"description":"Nombre del lead"},"last_name":{"type":"string","nullable":true,"description":"Apellido del lead"},"comments":{"type":"string","nullable":true,"description":"Comentarios sobre el lead"},"summary":{"type":"string","nullable":true,"description":"Resumen generado de la conversación"},"instagram_username":{"type":"string","nullable":true,"description":"Username de Instagram (si aplica)"},"variables":{"type":"object","description":"Variables personalizadas del lead","additionalProperties":{"type":"string"}},"smart_tags":{"type":"array","description":"Smart tags asignados al lead","items":{"$ref":"#/components/schemas/SmartTag"}},"moderator":{"$ref":"#/components/schemas/LeadModerator"},"ads":{"type":"array","description":"Anuncios de origen del lead (Meta/Instagram). Vacío si el contacto no proviene de un anuncio. Un objeto por ad_id único. Cada anuncio puede incluir el ctwa_clid del click más reciente a ese ad.","items":{"$ref":"#/components/schemas/LeadAd"}},"ctwa_clid":{"type":"string","nullable":true,"description":"Click ID de Click-to-WhatsApp (CTWA) más reciente del lead. `null` si el contacto no proviene de un anuncio de WhatsApp. Sirve para enviar conversiones a Meta (CAPI)."},"created_at":{"type":"string","format":"date-time","description":"Fecha de creación"},"updated_at":{"type":"string","format":"date-time","description":"Fecha de última actualización"},"last_message_at":{"type":"string","format":"date-time","nullable":true,"description":"Fecha del último mensaje"}}},"SmartTag":{"type":"object","description":"Smart tag asignado a un lead","properties":{"id":{"type":"string","description":"ID del smart tag"},"name":{"type":"string","description":"Nombre del smart tag"}}},"LeadModerator":{"type":"object","nullable":true,"description":"Moderador asignado al lead. `null` si no tiene uno.","properties":{"id":{"type":"string","description":"ID del usuario moderador"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}}},"LeadAd":{"type":"object","description":"Anuncio de origen asociado a un lead","properties":{"ad_id":{"type":"string","description":"ID del anuncio (source_id o ad_id de Meta)"},"ad":{"type":"string","nullable":true,"description":"Texto/body del anuncio"},"ctwa_clid":{"type":"string","nullable":true,"description":"Click ID de Click-to-WhatsApp asociado a este anuncio. `null` en referrals de Instagram u otros canales sin CTWA."}}},"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}},"paths":{"/leads/{id}":{"patch":{"tags":["Leads"],"summary":"Actualizar un lead","description":"Actualiza campos de un lead. Campos permitidos: email, first_name, last_name, comments, variables, phone_number y smart_tags. El campo phone_number solo puede ser actualizado si el tipo de conexión NO es whatsapp-business, whatsapp-lite o whatsapp-hybrid. Las variables son validadas: deben existir previamente en la organización y el valor debe coincidir con el tipo definido. Las smart tags se actualizan mediante una operación explícita: add, replace o remove.","parameters":[{"name":"id","in":"path","required":true,"description":"ID del lead","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadUpdateRequest"}}}},"responses":{"200":{"description":"Lead actualizado exitosamente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadUpdateResponse"}}}},"400":{"description":"Error de validación o campos no permitidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"No autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Lead no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```

## Obtener lead por tipo de conexión y contact\_id

> Obtiene un lead específico por su tipo de conexión e identificador de contacto. Útil cuando conoces el teléfono o username pero no el ID interno.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Leads"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"LeadResponse":{"type":"object","properties":{"success":{"type":"boolean"},"lead":{"$ref":"#/components/schemas/Lead"}}},"Lead":{"type":"object","description":"Representación de un lead/contacto","properties":{"id":{"type":"string","description":"ID único del lead"},"contact_id":{"type":"string","description":"Identificador del contacto (teléfono, username, etc)"},"connection_type":{"type":"string","description":"Tipo de conexión del lead","enum":["whatsapp-business","whatsapp-lite","whatsapp-hybrid","instagram","facebook","email","tiktok","mercado-libre"]},"phone_number":{"type":"string","nullable":true,"description":"Número de teléfono"},"email":{"type":"string","nullable":true,"description":"Email del lead"},"first_name":{"type":"string","nullable":true,"description":"Nombre del lead"},"last_name":{"type":"string","nullable":true,"description":"Apellido del lead"},"comments":{"type":"string","nullable":true,"description":"Comentarios sobre el lead"},"summary":{"type":"string","nullable":true,"description":"Resumen generado de la conversación"},"instagram_username":{"type":"string","nullable":true,"description":"Username de Instagram (si aplica)"},"variables":{"type":"object","description":"Variables personalizadas del lead","additionalProperties":{"type":"string"}},"smart_tags":{"type":"array","description":"Smart tags asignados al lead","items":{"$ref":"#/components/schemas/SmartTag"}},"moderator":{"$ref":"#/components/schemas/LeadModerator"},"ads":{"type":"array","description":"Anuncios de origen del lead (Meta/Instagram). Vacío si el contacto no proviene de un anuncio. Un objeto por ad_id único. Cada anuncio puede incluir el ctwa_clid del click más reciente a ese ad.","items":{"$ref":"#/components/schemas/LeadAd"}},"ctwa_clid":{"type":"string","nullable":true,"description":"Click ID de Click-to-WhatsApp (CTWA) más reciente del lead. `null` si el contacto no proviene de un anuncio de WhatsApp. Sirve para enviar conversiones a Meta (CAPI)."},"created_at":{"type":"string","format":"date-time","description":"Fecha de creación"},"updated_at":{"type":"string","format":"date-time","description":"Fecha de última actualización"},"last_message_at":{"type":"string","format":"date-time","nullable":true,"description":"Fecha del último mensaje"}}},"SmartTag":{"type":"object","description":"Smart tag asignado a un lead","properties":{"id":{"type":"string","description":"ID del smart tag"},"name":{"type":"string","description":"Nombre del smart tag"}}},"LeadModerator":{"type":"object","nullable":true,"description":"Moderador asignado al lead. `null` si no tiene uno.","properties":{"id":{"type":"string","description":"ID del usuario moderador"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}}},"LeadAd":{"type":"object","description":"Anuncio de origen asociado a un lead","properties":{"ad_id":{"type":"string","description":"ID del anuncio (source_id o ad_id de Meta)"},"ad":{"type":"string","nullable":true,"description":"Texto/body del anuncio"},"ctwa_clid":{"type":"string","nullable":true,"description":"Click ID de Click-to-WhatsApp asociado a este anuncio. `null` en referrals de Instagram u otros canales sin CTWA."}}},"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}},"paths":{"/leads/{connection_type}/{contact_id}":{"get":{"tags":["Leads"],"summary":"Obtener lead por tipo de conexión y contact_id","description":"Obtiene un lead específico por su tipo de conexión e identificador de contacto. Útil cuando conoces el teléfono o username pero no el ID interno.","parameters":[{"name":"connection_type","in":"path","required":true,"description":"Tipo de conexión","schema":{"type":"string","enum":["whatsapp-business","whatsapp-lite","whatsapp-hybrid","instagram","facebook","email","tiktok","mercado-libre"]}},{"name":"contact_id","in":"path","required":true,"description":"Identificador del contacto (teléfono, username, email, etc)","schema":{"type":"string"}}],"responses":{"200":{"description":"Lead obtenido exitosamente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadResponse"}}}},"400":{"description":"Tipo de conexión inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"No autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Lead no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```

## Etiquetar contactos en masa

> Agrega \`tag\_id\` a los contactos que cumplen los filtros. \`dry\_run: true\` devuelve cuántos se etiquetarían y no escribe. Sin \`dry\_run\` ejecuta la acción. Con \`trigger\_automations: true\` hay un máximo de contactos por pedido. \`filter\_tag\_mode\` acepta \`any\`, \`has\`, \`has\_not\` y \`no\_tags\`. \`variable\_mode\` acepta \`has\_value\`, \`no\_value\`, \`equals\`, \`contains\`, \`gte\` y \`lte\`.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Leads"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"BulkTagLeadsRequest":{"type":"object","required":["tag_id"],"properties":{"tag_id":{"type":"string"},"trigger_automations":{"type":"boolean","description":"Si es true, dispara las automatizaciones de la etiqueta."},"variable_name":{"type":"string"},"variable_mode":{"type":"string","enum":["has_value","no_value","equals","contains","gte","lte"]},"variable_value":{"description":"Valor comparado cuando el modo lo pide."},"filter_tag_id":{"type":"string"},"filter_tag_mode":{"type":"string","enum":["any","has","has_not","no_tags"],"default":"any"},"date_field":{"type":"string","enum":["created_at","last_message_at"],"default":"created_at"},"date_range":{"$ref":"#/components/schemas/DateRangeInput"},"dry_run":{"type":"boolean"}}},"DateRangeInput":{"type":"object","description":"Rango usado por las acciones masivas. Las fechas son AAAA-MM-DD o ISO 8601.","properties":{"start_date":{"type":"string"},"end_date":{"type":"string"},"start_time":{"type":"string"},"end_time":{"type":"string"}}},"BulkTagLeadsResponse":{"type":"object","properties":{"success":{"type":"boolean"},"dry_run":{"type":"boolean"},"tag":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"trigger_automations":{"type":"boolean"},"timezone":{"type":"string"},"matching":{"type":"integer"},"already_tagged":{"type":"integer"},"total":{"type":"integer"},"tagged":{"type":"integer"},"failed":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Unauthorized":{"description":"No autorizado (API Key ausente o inválida)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"InternalError":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"paths":{"/leads/tags":{"post":{"tags":["Leads"],"summary":"Etiquetar contactos en masa","description":"Agrega `tag_id` a los contactos que cumplen los filtros. `dry_run: true` devuelve cuántos se etiquetarían y no escribe. Sin `dry_run` ejecuta la acción. Con `trigger_automations: true` hay un máximo de contactos por pedido. `filter_tag_mode` acepta `any`, `has`, `has_not` y `no_tags`. `variable_mode` acepta `has_value`, `no_value`, `equals`, `contains`, `gte` y `lte`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkTagLeadsRequest"}}}},"responses":{"200":{"description":"Etiquetado ejecutado o vista previa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkTagLeadsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Activar o pausar el asistente en contactos filtrados

> Cambia el estado del asistente en las conversaciones que cumplen \`tag\_ids\`, \`moderator\_ids\` y \`date\_range\`. \`active\` es obligatorio. La operación se ejecuta al responder 200.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Leads"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"BulkToggleBotRequest":{"type":"object","required":["active"],"properties":{"active":{"type":"boolean"},"tag_ids":{"type":"array","items":{"type":"string"}},"moderator_ids":{"type":"array","items":{"type":"string"}},"date_range":{"$ref":"#/components/schemas/DateRangeInput"}}},"DateRangeInput":{"type":"object","description":"Rango usado por las acciones masivas. Las fechas son AAAA-MM-DD o ISO 8601.","properties":{"start_date":{"type":"string"},"end_date":{"type":"string"},"start_time":{"type":"string"},"end_time":{"type":"string"}}},"SuccessResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean"}}},"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Unauthorized":{"description":"No autorizado (API Key ausente o inválida)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"InternalError":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"paths":{"/leads/bot":{"post":{"tags":["Leads"],"summary":"Activar o pausar el asistente en contactos filtrados","description":"Cambia el estado del asistente en las conversaciones que cumplen `tag_ids`, `moderator_ids` y `date_range`. `active` es obligatorio. La operación se ejecuta al responder 200.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkToggleBotRequest"}}}},"responses":{"200":{"description":"Estado del asistente actualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Archivar conversaciones de un rango de fechas

> Archiva las conversaciones cuya actividad cae en \`date\_range\`. \`start\_date\` y \`end\_date\` son obligatorios. \`dry\_run: true\` cuenta sin archivar.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Leads"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"BulkArchiveRequest":{"type":"object","required":["date_range"],"properties":{"date_range":{"$ref":"#/components/schemas/DateRangeInput"},"dry_run":{"type":"boolean"}}},"DateRangeInput":{"type":"object","description":"Rango usado por las acciones masivas. Las fechas son AAAA-MM-DD o ISO 8601.","properties":{"start_date":{"type":"string"},"end_date":{"type":"string"},"start_time":{"type":"string"},"end_time":{"type":"string"}}},"BulkArchiveResponse":{"type":"object","properties":{"success":{"type":"boolean"},"dry_run":{"type":"boolean"},"matching":{"type":"integer"},"already_archived":{"type":"integer"},"archived":{"type":"integer"}}},"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Unauthorized":{"description":"No autorizado (API Key ausente o inválida)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"InternalError":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"paths":{"/leads/archive":{"post":{"tags":["Leads"],"summary":"Archivar conversaciones de un rango de fechas","description":"Archiva las conversaciones cuya actividad cae en `date_range`. `start_date` y `end_date` son obligatorios. `dry_run: true` cuenta sin archivar.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkArchiveRequest"}}}},"responses":{"200":{"description":"Archivado ejecutado o vista previa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkArchiveResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Exportar contactos a un archivo

> Genera un archivo con los contactos que cumplen \`tag\_ids\`, \`date\_range\` y, si se pide, \`potential\_clients\`. La respuesta incluye una URL para descargarlo.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Leads"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"ExportLeadsRequest":{"type":"object","properties":{"potential_clients":{"type":"boolean"},"tag_ids":{"type":"array","items":{"type":"string"}},"date_range":{"$ref":"#/components/schemas/DateRangeInput"}}},"DateRangeInput":{"type":"object","description":"Rango usado por las acciones masivas. Las fechas son AAAA-MM-DD o ISO 8601.","properties":{"start_date":{"type":"string"},"end_date":{"type":"string"},"start_time":{"type":"string"},"end_time":{"type":"string"}}},"ExportLeadsResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean"},"file":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"mimetype":{"type":"string"}}}}},"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Unauthorized":{"description":"No autorizado (API Key ausente o inválida)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"InternalError":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"paths":{"/leads/export":{"post":{"tags":["Leads"],"summary":"Exportar contactos a un archivo","description":"Genera un archivo con los contactos que cumplen `tag_ids`, `date_range` y, si se pide, `potential_clients`. La respuesta incluye una URL para descargarlo.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportLeadsRequest"}}}},"responses":{"200":{"description":"Archivo generado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportLeadsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Encolar un envío masivo de plantilla

> Encola el envío de la plantilla \`template\_id\` a los teléfonos de \`contacts\` o, si no hay lista, a los contactos que cumplen \`tag\_ids\` y \`date\_range\`. Un 200 significa que el envío quedó encolado. Requiere la extensión de envío masivo y una línea capaz de enviar plantillas. No hay vista previa.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Leads"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"MassSendRequest":{"type":"object","required":["template_id"],"properties":{"template_id":{"type":"string"},"tag_ids":{"type":"array","items":{"type":"string"}},"date_range":{"$ref":"#/components/schemas/DateRangeInput"},"contacts":{"type":"array","description":"Teléfonos explícitos. Si hay lista, no se usan los filtros.","items":{"type":"string"}}}},"DateRangeInput":{"type":"object","description":"Rango usado por las acciones masivas. Las fechas son AAAA-MM-DD o ISO 8601.","properties":{"start_date":{"type":"string"},"end_date":{"type":"string"},"start_time":{"type":"string"},"end_time":{"type":"string"}}},"SuccessResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean"}}},"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Unauthorized":{"description":"No autorizado (API Key ausente o inválida)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"InternalError":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"paths":{"/leads/messages":{"post":{"tags":["Leads"],"summary":"Encolar un envío masivo de plantilla","description":"Encola el envío de la plantilla `template_id` a los teléfonos de `contacts` o, si no hay lista, a los contactos que cumplen `tag_ids` y `date_range`. Un 200 significa que el envío quedó encolado. Requiere la extensión de envío masivo y una línea capaz de enviar plantillas. No hay vista previa.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MassSendRequest"}}}},"responses":{"200":{"description":"Envío encolado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```