Leads

Endpoints para crear, buscar, actualizar y mover leads (negocios) en el embudo, además de tags, secuencias y envío de WhatsApp por lead.

Base URLhttps://app.syncro.chat/api/v1AuthX-API-Key: crm_SUA_CHAVE_AQUI

El objeto Lead

La mayoría de los endpoints devuelve el lead en este formato base (los campos adicionales se agregan mediante ?include):

{
  "id": 123,
  "name": "João Silva",
  "phone": "+5511999887766",
  "email": "[email protected]",
  "company": "ACME",
  "birthday": "1990-01-15",
  "value": 5000.0,
  "source": "site",
  "tags": ["vip", "enterprise"],
  "pipeline_id": 1,
  "stage_id": 5,
  "notes": "Anotações do lead",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "verao_2026",
  "utm_term": null,
  "utm_content": null,
  "stage": { "id": 5, "name": "Proposta" },
  "pipeline": { "id": 1, "name": "Vendas" },
  "created_at": "2026-06-30T10:00:00Z",
  "custom_fields": { "tamanho_empresa": "100+" }
}

Listar leads

GET/leads

Permiso: leads:read

Lista los leads de la cuenta, paginado, con filtros.

Parámetros de query

pipeline_idintegeropcional

Filtra por pipeline

stage_idintegeropcional

Filtra por etapa

assigned_tointegeropcional

Filtra por el ID del responsable

sourcestringopcional

Filtra por la origen

statusstringopcional

Filtra por el status

tagsarrayopcional

Tags (nombres); devuelve leads con **cualquiera** de ellas

qstringopcional

Busca por nombre, correo o teléfono

updated_sincedate (ISO 8601)opcional

Solo leads modificados a partir de esta fecha (ideal para sync)

created_fromdateopcional

Creados a partir de

created_todateopcional

Creados hasta

pageintegeropcional

Página (predeterminado 1)

per_pageintegeropcional

Elementos por página (predeterminado 50, máx 200)

includestringopcional

Relaciones extra separadas por coma (ver abajo)

Solicitud

curl "https://app.syncro.chat/api/v1/leads?pipeline_id=1&per_page=2&include=owner" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Respuesta

{
  "success": true,
  "data": [
    {
      "id": 123,
      "name": "João Silva",
      "phone": "+5511999887766",
      "email": "[email protected]",
      "company": "ACME",
      "value": 5000,
      "source": "site",
      "tags": [
        "vip"
      ],
      "pipeline_id": 1,
      "stage_id": 5,
      "stage": {
        "id": 5,
        "name": "Proposta"
      },
      "pipeline": {
        "id": 1,
        "name": "Vendas"
      },
      "created_at": "2026-06-30T10:00:00Z",
      "custom_fields": {},
      "assigned_to": 12,
      "owner": {
        "id": 12,
        "name": "Ana",
        "email": "[email protected]"
      }
    }
  ],
  "meta": {
    "total": 250,
    "per_page": 2,
    "current_page": 1,
    "last_page": 125,
    "has_more": true
  }
}

Crear lead

POST/leads

Permiso: leads:write

Crea un nuevo lead.

Parámetros del body

namestringobligatorio

Nombre del lead

pipeline_idintegerobligatorio

Pipeline de destino

stage_idintegerobligatorio

Etapa de destino

phonestringopcional

Teléfono (E.164 recomendado)

emailstringopcional

Correo

valuenumberopcional

Valor del negocio

sourcestringopcional

Origen

tagsarray(string)opcional

Crear o actualizar lead (upsert)

POST/leads/upsert

Permiso: leads:write

Crea un lead nuevo o actualiza uno existente, casando por correo y/o teléfono. Ideal para sincronización. Acepta los mismos campos de POST /leads, más el campo de abajo.

Parámetros del body

match_bystringopcional

email, phone o email_or_phone (predeterminado email_or_phone)

Es obligatorio enviar correo o teléfono (es la clave de match). En update, solo se cambian los campos enviados (no vacíos).

Solicitud

curl -X POST "https://app.syncro.chat/api/v1/leads/upsert" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "[email protected]",
    "pipeline_id": 1,
    "stage_id": 5,
    "match_by": "email"
  }'

Respuesta

{
  "success": true,
  "created": true,
  "lead": {
    "id": 123,
    "name": "João Silva",
    "stage_id": 5
  }
}

Buscar lead por ID

GET/leads/123

Permiso: leads:read

Devuelve un lead. Acepta ?include= para cargar relaciones.

Solicitud

curl "https://app.syncro.chat/api/v1/leads/123?include=owner%2Ctasks%2Cnotes" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Respuesta

{
  "success": true,
  "lead": {
    "id": 123,
    "name": "João Silva",
    "stage_id": 5
  }
}

Mover lead de etapa

PUT/leads/123/stage

Permiso: leads:write

Mueve el lead a otra etapa (y pipeline).

Parámetros del body

stage_idintegerobligatorio

Nueva etapa

pipeline_idintegerobligatorio

Pipeline de la etapa

Errores: 422 con blocked: true y pending_tasks si la etapa actual tiene tareas obligatorias pendientes.

Solicitud

curl -X PUT "https://app.syncro.chat/api/v1/leads/123/stage" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": 7,
    "pipeline_id": 1
  }'

Respuesta

{
  "success": true,
  "lead_id": 123
}

Marcar como ganado

PUT/leads/123/won

Permiso: leads:write

Mueve el lead a una etapa de ganado y registra la venta.

Parámetros del body

stage_idintegerobligatorio

Etapa de ganado (debe tener is_won = true)

valuenumberopcional

Valor de la venta (si se omite, usa el valor del lead)

Errores: 422 si la etapa no es de ganado ("A etapa informada não é uma etapa de ganho.") o 422 blocked por tareas obligatorias pendientes.

Solicitud

curl -X PUT "https://app.syncro.chat/api/v1/leads/123/won" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": 10,
    "value": 7500
  }'

Respuesta

{
  "success": true,
  "lead_id": 123
}

Marcar como perdido

PUT/leads/123/lost

Permiso: leads:write

Mueve el lead a una etapa de pérdida y registra el motivo.

Parámetros del body

stage_idintegerobligatorio

Etapa de pérdida (debe tener is_lost = true)

reason_idintegeropcional

ID del motivo de pérdida (ver lost_reasons en [Pipelines](/es/pipelines))

Errores: 422 si la etapa no es de pérdida; 422 blocked por tareas pendientes.

Solicitud

curl -X PUT "https://app.syncro.chat/api/v1/leads/123/lost" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": 11,
    "reason_id": 3
  }'

Respuesta

{
  "success": true,
  "lead_id": 123
}

Eliminar lead

DELETE/leads/123

Permiso: leads:write

Elimina el lead.

Solicitud

curl -X DELETE "https://app.syncro.chat/api/v1/leads/123" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Respuesta

{
  "success": true
}

Agregar tags

POST/leads/123/tags

Permiso: leads:write

Agrega tags al lead (mantiene las existentes).

Parámetros del body

tagsarray(string)obligatorio

Nombres de las tags (mín. 1)

Solicitud

curl -X POST "https://app.syncro.chat/api/v1/leads/123/tags" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      "vip",
      "enterprise"
    ]
  }'

Respuesta

{
  "success": true,
  "lead_id": 123,
  "tags": [
    "vip",
    "enterprise"
  ]
}

Eliminar una tag

DELETE/leads/123/tags/vip

Permiso: leads:write

Elimina una tag por el nombre.

Solicitud

curl -X DELETE "https://app.syncro.chat/api/v1/leads/123/tags/vip" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Respuesta

{
  "success": true,
  "lead_id": 123,
  "tags": [
    "enterprise"
  ]
}

Inscribir en secuencia de nutrición

POST/leads/123/enroll-sequence

Permiso: sequences:write

Inscribe el lead en una secuencia activa. Ve la lista de secuencias en Secuencias.

Parámetros del body

sequence_idintegerobligatorio

ID de la secuencia (debe estar activa)

Solicitud

curl -X POST "https://app.syncro.chat/api/v1/leads/123/enroll-sequence" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "sequence_id": 1
  }'

Respuesta

{
  "success": true,
  "lead_id": 123,
  "sequence_id": 1,
  "lead_sequence_id": 45,
  "status": "active",
  "next_step_at": "2026-07-01T10:00:00Z"
}

Eliminar de secuencia

DELETE/leads/123/enroll-sequence/1

Permiso: sequences:write

Quita el lead de una secuencia.

Solicitud

curl -X DELETE "https://app.syncro.chat/api/v1/leads/123/enroll-sequence/1" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Respuesta

{
  "success": true,
  "lead_id": 123,
  "sequence_id": 1,
  "status": "exited_manual"
}

Enviar WhatsApp (texto o imagen)

POST/leads/123/send-whatsapp

Permiso: whatsapp:write

Envía un mensaje de texto o imagen al teléfono del lead. Ve números conectados en WhatsApp.

Parámetros del body

typestringobligatorio

text o image

bodystringcondicional

Texto del mensaje (obligatorio si no hay media_url)

media_urlstring (URL)condicional

URL de la imagen (obligatorio cuando type=image)

captionstringopcional

Leyenda de la imagen

instance_idintegeropcional

Número a usar (si se omite, usa el principal)

Errores: 422 si el lead no tiene teléfono; 422 con skip_reason: "window_closed" en números de la API Oficial fuera de la ventana de 24h (usa template); 502 en falla del proveedor.

Solicitud

curl -X POST "https://app.syncro.chat/api/v1/leads/123/send-whatsapp" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "body": "Olá! Tudo bem?",
    "instance_id": 1
  }'

Respuesta

{
  "success": true,
  "conversation_id": 99,
  "message_id": 456,
  "provider_msg_id": "wamid.xyz123"
}

Enviar template (HSM)

POST/leads/123/send-whatsapp-template

Permiso: whatsapp:write

Envía un template oficial aprobado (necesario fuera de la ventana de 24h en la API Oficial). Ve templates en WhatsApp.

Parámetros del body

template_idintegerobligatorio

ID del template (debe estar APPROVED)

variablesarray(string)opcional

Variables del cuerpo, en orden

header_media_urlstring (URL)opcional

Medios del encabezado, cuando el template lo exige

instance_idintegeropcional

Número a usar

Solicitud

curl -X POST "https://app.syncro.chat/api/v1/leads/123/send-whatsapp-template" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": 1,
    "variables": [
      "João",
      "Proposta",
      "30/07"
    ],
    "instance_id": 2
  }'

Respuesta

{
  "success": true,
  "conversation_id": 99,
  "message_id": 457,
  "provider_msg_id": "wamid.xyz456",
  "template_name": "lembrete_proposta"
}

Relaciones extra (`?include`)

En GET /leads y GET /leads/{id}, usa ?include= con nombres separados por coma para cargar datos adicionales. Los tokens desconocidos se ignoran.

include	Lo que agrega
`owner`	`assigned_to` (int) + `owner` `{id, name, email}`
`products`	`products[]` `{id, product_id, product_name, quantity, unit_price, discount_percent, total}`
`contacts`	`contacts[]` `{id, name, role, phone, email, is_primary}`
`notes`	`notes_list[]` `{id, body, author, created_at}`
`sales`	`sales[]` `{id, pipeline_id, value, closed_by, closed_at}` + `lost_sales[]` `{id, pipeline_id, reason_id, lost_at, lost_by}`
`tasks`	`tasks[]` `{id, subject, type, status, priority, due_date, due_time, completed_at, assigned_to}`
`sequences`	`active_sequence` `{id, name, current_step, total_steps, status}` + `sequences[]` `{id, sequence_id, name, status, next_step_at}`
`score`	`score` (int) + `score_updated_at`
`siblings`	`siblings[]` (otros negocios del mismo contacto) + `contact_totals`
`events`	`events[]` `{id, event_type, description, performed_by, created_at}`
`conversation`	`conversation` `{id, phone, status, last_message_at, unread_count, instance_id}`

events, conversation y siblings solo están disponibles en GET /leads/{id} (no en el listado, por costo).