# Leads

> Listar, filtrar y actualizar tus leads, añadir notas, pasar una conversación a una persona y enlazar cada lead con tu CRM.

Source: https://docs.whatsetter.com/es/developers/guides/leads/

Un lead es una persona con la que habla tu setter IA. La API expone la misma ficha que la pestaña **Leads** del dashboard: etapa (`status`), etiquetas (`tags`), responsable, próxima acción, resultado comercial y notas.

## Endpoints

| Método | Ruta | Scope |
|---|---|---|
| GET | [`/leads`](/api-reference/operations/listleads/) | `leads:read` |
| GET | [`/leads/{id}`](/api-reference/operations/getlead/) | `leads:read` |
| PATCH | [`/leads/{id}`](/api-reference/operations/updatelead/) | `leads:write` |
| GET | [`/leads/{id}/notes`](/api-reference/operations/listleadnotes/) | `leads:read` |
| POST | [`/leads/{id}/notes`](/api-reference/operations/createleadnote/) | `leads:write` |
| POST | [`/leads/{id}/handoff`](/api-reference/operations/handofflead/) | `leads:write` |
| POST | [`/leads/{id}/resume`](/api-reference/operations/resumelead/) | `leads:write` |

## Lo que cambia lo que hace el agente

Un lead lleva una etapa (`status`) y etiquetas (`tags`). Solo la etapa guía
al agente.

| Campo | Efecto en el agente |
|---|---|
| `status` | La etapa con la que trabaja el agente. La pone él mismo, según lo que dice su prompt, y respeta una etapa puesta por una persona o por tus herramientas: `qualified`, deja de cualificar; `not_interested` y `stopped`, ya no escribe; `cold`, deja de insistir; `in_progress`, retoma. |
| `tags` | Ninguno. Una etiqueta nunca detiene al agente, nunca cualifica un lead y nunca le hace proponer una cita. Las etiquetas sirven para ordenar: filtros, exportación, avisos, seguimientos limitados a algunas etiquetas, tu CRM. |
| `handoff`, `resume` | Detienen al agente en este lead, y luego lo dejan responder de nuevo. Mira más abajo. |

Una etiqueta con el nombre de una etapa, por ejemplo `"qualified"` en `tags`,
no cualifica al lead: envía `"status": "qualified"`. Para cambiar cuándo el
agente cualifica sus leads por sí solo, edita su prompt: mira
[Decidir cuándo un lead está cualificado](/es/dashboard/prompt/#decidir-cuándo-un-lead-está-cualificado).

## Listar y filtrar leads

Los leads llegan del más recientemente activo al más antiguo, 25 por página por defecto.

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/leads?status=qualified&campaign_id=acme-espana-1-ab12&limit=25" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch(
  'https://app.whatsetter.com/api/v1/leads?status=qualified&campaign_id=acme-espana-1-ab12&limit=25',
  { headers: { Authorization: 'Bearer ws_live_…' } },
);
const { data, pagination } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/leads",
    params={"status": "qualified", "campaign_id": "acme-espana-1-ab12", "limit": 25},
    headers={"Authorization": "Bearer ws_live_…"},
)
data = r.json()["data"]
```

```json
{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "phone": "34612345678",
      "whatsapp_id": "34612345678@c.us",
      "name": "Julien",
      "status": "qualified",
      "qualified": true,
      "qualified_at": "2026-09-12T10:04:31.000Z",
      "replied": true,
      "campaign_id": "acme-espana-1-ab12",
      "list_id": null,
      "channel": "whatsapp",
      "ig_username": null,
      "external_reference": "4471",
      "source": "api",
      "source_confidence": null,
      "tracked_link_id": null,
      "email": "julien@example.com",
      "tags": ["hot", "demo"],
      "messages_count": 14,
      "booking_status": "booked",
      "first_contact_at": "2026-09-10T08:00:12.000Z",
      "last_message_at": "2026-09-18T16:42:05.000Z",
      "last_message_direction": "inbound",
      "assigned_to": "66a1b2c3d4e5f6a7b8c9d0e1",
      "stage": "booked",
      "deal_status": "open",
      "lost_reason": null,
      "next_action_at": "2026-09-22T09:00:00.000Z",
      "next_action_label": "Volver a llamar",
      "created_at": "2026-09-10T07:59:58.000Z",
      "updated_at": "2026-09-18T16:42:05.000Z"
    }
  ],
  "pagination": { "has_more": true, "next_cursor": "66f1a2b3c4d5e6f7a8b9c0d1" }
}
```

`phone` son solo dígitos, sin el `+`. Pasa `cursor=next_cursor` para obtener la página siguiente.

### Filtros

| Parámetro | Qué hace |
|---|---|
| `status` | Uno de los estados de abajo. `qualified` devuelve todos los leads calificados en algún momento (su fecha de calificación está rellena). |
| `campaign_id` | El slug `campaign_id` de la campaña o su `id`, ambos vienen de [`GET /campaigns`](/api-reference/operations/listcampaigns/). |
| `phone` | Búsqueda exacta, formato internacional (`+34612345678`). |
| `external_reference` | Búsqueda exacta sobre el identificador que enviaste con `POST /campaigns/{id}/leads`. |
| `source` | De dónde viene el lead: `instagram`, `facebook`, `tiktok`, `youtube`, `linkedin`, `x`, `snapchat`, `pinterest`, `google`, `website`, `email`, `sms`, `qr`, `ads`, `other`, `direct`, `list`, `api`, `webhook`, `inbound`, `manual`, `messenger` (escribió a una página de Facebook en Messenger). |
| `tracked_link_id` | Solo los leads traídos por este [enlace rastreado](/es/developers/guides/links/). |
| `channel` | `whatsapp`, `instagram` o `facebook` (Messenger, a través de una página de Facebook). |
| `since` | Solo los leads activos después de esta fecha ISO 8601 (sobre `last_message_at`). |
| `limit`, `cursor` | Paginación, de 1 a 100 por página. |

> **Las campañas de grupo quedan fuera**
Sin filtro `campaign_id`, los leads de las campañas de grupo (los participantes) no se listan, igual que en el dashboard. Pasa el id de la campaña de grupo para verlos.

### Valores de estado

| `status` | Significado |
|---|---|
| `queued` | Importado, esperando su primer mensaje. |
| `pending` | Aún sin contactar: el primer mensaje del lead se retuvo y nunca salió. No hay conversación, y nadie tiene que hacer nada. |
| `in_progress` | La conversación está en marcha. |
| `qualified` | El agente validó el interés, o lo fijaste desde la API. |
| `not_interested` | Perfil equivocado o rechazo explícito. |
| `cold` | El agente escribió primero y el lead aún no ha respondido. Con su primera respuesta, pasa a `in_progress`. También se pone cuando una persona marca el lead sin respuesta. |
| `stopped` | La conversación se detuvo. |
| `unknown` | Un valor interno que la API pública no nombra. |

## Leer un lead

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1', {
  headers: { Authorization: 'Bearer ws_live_…' },
});
const { data: lead } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1",
    headers={"Authorization": "Bearer ws_live_…"},
)
lead = r.json()["data"]
```

La respuesta es `{ "data": lead }` con el mismo objeto de arriba. Un lead de otro espacio de trabajo responde `404`, nunca `403`.

## Actualizar un lead

Envía solo los campos que cambias. Se necesita al menos uno.

**cURL**

```bash
curl -X PATCH "https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1" \
  -H "Authorization: Bearer ws_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "qualified",
    "tags": ["hot", "demo"],
    "assigned_to": "66a1b2c3d4e5f6a7b8c9d0e1",
    "next_action_at": "2026-09-22T09:00:00.000Z",
    "next_action_label": "Volver a llamar"
  }'
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1', {
  method: 'PATCH',
  headers: { Authorization: 'Bearer ws_live_…', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    status: 'qualified',
    tags: ['hot', 'demo'],
    assigned_to: '66a1b2c3d4e5f6a7b8c9d0e1',
    next_action_at: '2026-09-22T09:00:00.000Z',
    next_action_label: 'Volver a llamar',
  }),
});
const { data: lead } = await res.json();
```

**Python**

```python
import requests

r = requests.patch(
    "https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1",
    headers={"Authorization": "Bearer ws_live_…"},
    json={
        "status": "qualified",
        "tags": ["hot", "demo"],
        "assigned_to": "66a1b2c3d4e5f6a7b8c9d0e1",
        "next_action_at": "2026-09-22T09:00:00.000Z",
        "next_action_label": "Volver a llamar",
    },
)
lead = r.json()["data"]
```

La respuesta es el lead actualizado, `200`.

| Campo | Reglas |
|---|---|
| `status` | `qualified`, `in_progress`, `not_interested`, `cold`, `pending`, `stopped` o `queued`. Fijar `qualified` rellena `qualified_at` una sola vez. |
| `tags` | Array de hasta 20 cadenas, 40 caracteres cada una. Sustituye toda la lista. Las etiquetas vacías o demasiado largas se descartan, los duplicados se eliminan. Nunca cambia lo que hace el agente: mira las etiquetas del agente más abajo. |
| `assigned_to` | Un id de miembro de [`GET /team/members`](/api-reference/operations/listteammembers/), o `null` para quitar el responsable. Id desconocido: `422`. |
| `next_action_at` | Fecha ISO 8601, o `null`. |
| `next_action_label` | Hasta 80 caracteres, o `null`. Necesita una fecha `next_action_at` (422 si falta). Borrar la fecha borra el texto. |
| `deal_status` | `open`, `won` o `lost`. |
| `lost_reason` | Uno de `price`, `timing`, `unqualified`, `competitor`, `unreachable`, `other`. Obligatorio con `deal_status: "lost"`, se borra con `open` y `won`. |

Cada cambio escribe el historial del lead, los mismos eventos que escribe el dashboard (`owner`, `next_action`, `outcome`), con el nombre de tu clave API como autor.

### `tags` y las etiquetas del agente

Cuando el agente del lead tiene sus etiquetas activadas, pone él mismo
algunas etiquetas (mira [Etiquetas del agente](/es/dashboard/labels/)).
`tags` las contiene junto con las que ponen las personas. Un `PATCH` con
`tags` cuenta como un cambio a mano, como en el dashboard:

- quitar una de las etiquetas del agente, o añadir una de sus etiquetas, pasa las etiquetas de este lead a las personas: el agente deja de cambiarlas. Devuélveselas en el dashboard con **Devolver al agente**;
- una etiqueta tuya, como `"VIP"`, no cambia nada para el agente;
- el nombre de una de las etiquetas del agente se guarda con la ortografía del agente, sea cual sea la mayúscula que envíes. Con **Una etiqueta principal**, la etiqueta principal que añades sustituye a la anterior del lead.

Si no se pueden leer los ajustes de etiquetas del agente, la llamada responde
`503 tag_rules_unavailable` y no se escribe nada: inténtalo de nuevo en un
momento.

## Notas

Las notas son los textos libres que tu equipo ve en la ficha del lead.

**cURL**

```bash
curl -X POST "https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1/notes" \
  -H "Authorization: Bearer ws_live_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"Le devolví la llamada, quiere un presupuesto antes del viernes."}'
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1/notes', {
  method: 'POST',
  headers: { Authorization: 'Bearer ws_live_…', 'Content-Type': 'application/json' },
  body: JSON.stringify({ text: 'Le devolví la llamada, quiere un presupuesto antes del viernes.' }),
});
const { data: note } = await res.json();
```

**Python**

```python
import requests

r = requests.post(
    "https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1/notes",
    headers={"Authorization": "Bearer ws_live_…"},
    json={"text": "Le devolví la llamada, quiere un presupuesto antes del viernes."},
)
note = r.json()["data"]
```

```json
{
  "data": {
    "id": "66f1a2b3c4d5e6f7a8b9c0e2",
    "text": "Le devolví la llamada, quiere un presupuesto antes del viernes.",
    "author": "API · Mi CRM",
    "created_at": "2026-09-19T08:12:00.000Z"
  }
}
```

`text` tiene de 1 a 2000 caracteres. El autor es `API · <nombre de la clave>` para las notas que creas, o el nombre del compañero para las notas escritas en el dashboard. `GET /leads/{id}/notes` devuelve `{ "data": [ ...notas ] }`, las más recientes primero, hasta 100.

## Pasar una conversación a una persona y devolverla

`POST /leads/{id}/handoff` detiene al agente IA en este lead. Se queda en silencio hasta que llames a `POST /leads/{id}/resume`. Es el mismo interruptor que la toma de control del dashboard, así que los dos nunca se contradicen.

**cURL**

```bash
curl -X POST "https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1/handoff" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1/handoff', {
  method: 'POST',
  headers: { Authorization: 'Bearer ws_live_…' },
});
const { data: control } = await res.json();
```

**Python**

```python
import requests

r = requests.post(
    "https://app.whatsetter.com/api/v1/leads/66f1a2b3c4d5e6f7a8b9c0d1/handoff",
    headers={"Authorization": "Bearer ws_live_…"},
)
control = r.json()["data"]
```

```json
{
  "data": {
    "id": "66f1a2b3c4d5e6f7a8b9c0d1",
    "external_reference": "4471",
    "agent_active": false,
    "manual_override": true,
    "status": "in_progress",
    "dashboard_synced": true,
    "updated_at": "2026-09-19T08:12:00.000Z"
  }
}
```

- El `status` del lead se conserva: tomar el control nunca marca un lead como detenido o calificado.
- Las dos llamadas son idempotentes: un segundo handoff sobre un lead ya tomado responde `200`.
- `dashboard_synced: false` significa que el agente está detenido pero la lista de Leads puede ir con retraso. La vista de conversación siempre es correcta.
- La regla de estado: handoff y resume solo se aplican a leads con los que el agente ya ha hablado (`in_progress`, `stopped`, `cold`, `qualified`, `not_interested`). Un lead `queued` o `pending` no tiene conversación que pasar y responde `409 invalid_state`.
- En Instagram y Messenger el interruptor se escribe en el propio lead, donde lo leen sus motores, igual que **Tomar el control** en el dashboard. `resume` también termina la pausa abierta por la respuesta de una persona (`agent_paused_until` en [`GET /conversations`](/es/developers/guides/conversations/)).

> **Enviar mientras el agente está detenido**
Tras un handoff, tus propios mensajes van por [`POST /messages`](/es/developers/guides/messages/). El agente no responderá al lead hasta que lo reactives.

## El campo stage

`stage` es de solo lectura y se deriva del lead exactamente como el embudo del dashboard. Responde en una palabra a «¿dónde está esta persona comercialmente?», mientras que `status` es el vocabulario propio de la IA.

| `stage` | Cuándo |
|---|---|
| `contacted` | Aún sin respuesta contada, y no `cold`: por ejemplo una persona que escribió primero y aún no tiene respuesta. |
| `conversation` | El lead respondió, la IA o una persona le está hablando. |
| `waiting` | Aún sin contactar: el primer mensaje se retuvo y nunca salió (`status: pending`). |
| `qualified` | Interés validado (`status: qualified`). |
| `booked` | Hay una reunión en el calendario, o ya se celebró. Gana a cualquier otro valor. |
| `not_interested` | Perfil equivocado o rechazo. |
| `cold` | El agente escribió primero, aún sin respuesta (`status: cold`). |
| `stopped` | La conversación se detuvo. |

## Enlazar con tu CRM

Envía el identificador de tu propia ficha en `external_reference` cuando empujes un lead opt-in con [`POST /campaigns/{id}/leads`](/es/developers/guides/campaigns/). WhatSetter lo guarda tal cual, lo devuelve en cada lead y cada webhook, y te deja buscarlo:

```bash
curl "https://app.whatsetter.com/api/v1/leads?external_reference=4471" \
  -H "Authorization: Bearer ws_live_…"
```

`external_reference` es `null` para los leads que no vienen de ti (importaciones CSV, importaciones de lista, formularios de página de venta). Para esos, compara por `phone`: solo dígitos en ambos lados.

## Errores que encontrarás

| HTTP | `code` | Cuándo |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Clave ausente, desconocida o revocada. |
| 403 | `insufficient_scope` | La clave no tiene `leads:read` o `leads:write`. |
| 404 | `not_found` | Lead desconocido, o lead de otro espacio de trabajo. |
| 409 | `invalid_state` | Handoff o resume sobre un lead nunca contactado. |
| 422 | `validation_error` | Estado desconocido, teléfono inválido, id de miembro desconocido, cuerpo vacío, cursor inválido o caducado. |
| 503 | `tag_rules_unavailable` | Un cambio de `tags` mientras no se podían leer los ajustes de etiquetas del agente. No se escribió nada. Puedes reintentar. |
| 429 | `rate_limited` | Demasiadas peticiones este minuto. Respeta `Retry-After`. |
| 502 | `upstream_error` | El flujo de control del agente no estaba disponible. Puedes reintentar. |

## Relacionado

- [Campañas: empujar un lead opt-in](/es/developers/guides/campaigns/)
- [Mensajes: escribir a un lead](/es/developers/guides/messages/)
- [Leads en el dashboard](/es/dashboard/leads/)
- [Webhooks firmados](/es/developers/webhooks/)
