# Leads

> Lister, filtrer et mettre à jour tes leads, ajouter des notes, passer une conversation à un humain et relier chaque lead à ton CRM.

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

Un lead, c'est une personne à qui ton setter IA parle. L'API expose la même fiche que l'onglet **Leads** du dashboard : étape (`status`), étiquettes (`tags`), propriétaire, prochaine action, résultat commercial et notes.

## Endpoints

| Méthode | Chemin | 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` |

## Ce qui change ce que fait l'agent

Un lead porte une étape (`status`) et des étiquettes (`tags`). Seule l'étape
pilote l'agent.

| Champ | Effet sur l'agent |
|---|---|
| `status` | L'étape d'après laquelle l'agent travaille. Il la pose lui-même, d'après ce que dit son prompt, et il respecte une étape posée par une personne ou par tes outils : `qualified`, il arrête de qualifier ; `not_interested` et `stopped`, il n'écrit plus ; `cold`, il n'insiste plus ; `in_progress`, il reprend. |
| `tags` | Aucun. Une étiquette n'arrête jamais l'agent, ne qualifie jamais un lead et ne lui fait jamais proposer de rendez-vous. Les étiquettes servent à trier : filtres, export, notifications, relances limitées à certaines étiquettes, ton CRM. |
| `handoff`, `resume` | Arrêtent l'agent sur ce lead, puis le laissent répondre de nouveau. Vois plus bas. |

Une étiquette qui porte le nom d'une étape, par exemple `"qualified"` dans
`tags`, ne qualifie pas le lead : envoie `"status": "qualified"`. Pour changer
quand l'agent qualifie ses leads tout seul, modifie son prompt : vois
[Décider quand un lead est qualifié](/fr/dashboard/prompt/#décider-quand-un-lead-est-qualifié).

## Lister et filtrer les leads

Les leads arrivent du plus récemment actif au plus ancien, 25 par page par défaut.

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/leads?status=qualified&campaign_id=acme-france-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-france-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-france-1-ab12", "limit": 25},
    headers={"Authorization": "Bearer ws_live_…"},
)
data = r.json()["data"]
```

```json
{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "phone": "33612345678",
      "whatsapp_id": "33612345678@c.us",
      "name": "Julien",
      "status": "qualified",
      "qualified": true,
      "qualified_at": "2026-09-12T10:04:31.000Z",
      "replied": true,
      "campaign_id": "acme-france-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": "Rappeler",
      "created_at": "2026-09-10T07:59:58.000Z",
      "updated_at": "2026-09-18T16:42:05.000Z"
    }
  ],
  "pagination": { "has_more": true, "next_cursor": "66f1a2b3c4d5e6f7a8b9c0d1" }
}
```

`phone` ne contient que des chiffres, sans le `+`. Passe `cursor=next_cursor` pour obtenir la page suivante.

### Filtres

| Paramètre | Effet |
|---|---|
| `status` | Un des statuts ci-dessous. `qualified` renvoie tous les leads qualifiés à un moment donné (leur date de qualification est renseignée). |
| `campaign_id` | Le slug `campaign_id` de la campagne ou son `id`, les deux viennent de [`GET /campaigns`](/api-reference/operations/listcampaigns/). |
| `phone` | Recherche exacte, format international (`+33612345678`). |
| `external_reference` | Recherche exacte sur l'identifiant que tu as envoyé avec `POST /campaigns/{id}/leads`. |
| `source` | D'où vient le lead : `instagram`, `facebook`, `tiktok`, `youtube`, `linkedin`, `x`, `snapchat`, `pinterest`, `google`, `website`, `email`, `sms`, `qr`, `ads`, `other`, `direct`, `list`, `api`, `webhook`, `inbound`, `manual`, `messenger` (a écrit à une Page Facebook sur Messenger). |
| `tracked_link_id` | Seulement les leads amenés par ce [lien traqué](/fr/developers/guides/links/). |
| `channel` | `whatsapp`, `instagram` ou `facebook` (Messenger, via une Page Facebook). |
| `since` | Seulement les leads actifs après cette date ISO 8601 (sur `last_message_at`). |
| `limit`, `cursor` | Pagination, 1 à 100 par page. |

> **Les campagnes de groupe restent à part**
Sans filtre `campaign_id`, les leads des campagnes de groupe (les participants) ne sont pas listés, comme dans le dashboard. Passe l'id de la campagne de groupe pour les voir.

### Valeurs de statut

| `status` | Signification |
|---|---|
| `queued` | Importé, en attente de son premier message. |
| `pending` | Pas encore contacté : le premier message du lead a été retenu et n'est jamais parti. Il n'y a pas de conversation, et personne n'a rien à faire. |
| `in_progress` | La conversation est en cours. |
| `qualified` | L'agent a validé l'intérêt, ou tu l'as posé depuis l'API. |
| `not_interested` | Mauvaise cible ou refus explicite. |
| `cold` | L'agent a écrit en premier et le lead n'a pas encore répondu. À sa première réponse, il passe à `in_progress`. Posé aussi quand une personne marque le lead sans réponse. |
| `stopped` | La conversation a été arrêtée. |
| `unknown` | Une valeur interne que l'API publique ne nomme pas. |

## Lire 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 réponse est `{ "data": lead }` avec le même objet que ci-dessus. Un lead d'un autre espace de travail répond `404`, jamais `403`.

## Mettre à jour un lead

N'envoie que les champs que tu changes. Il en faut au moins un.

**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": "Rappeler"
  }'
```

**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: 'Rappeler',
  }),
});
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": "Rappeler",
    },
)
lead = r.json()["data"]
```

La réponse est le lead mis à jour, `200`.

| Champ | Règles |
|---|---|
| `status` | `qualified`, `in_progress`, `not_interested`, `cold`, `pending`, `stopped` ou `queued`. Poser `qualified` renseigne `qualified_at` une seule fois. |
| `tags` | Tableau de 20 chaînes maximum, 40 caractères chacune. Remplace toute la liste. Les étiquettes vides ou trop longues sont ignorées, les doublons retirés. Ne change jamais ce que fait l'agent : vois les étiquettes de l'agent plus bas. |
| `assigned_to` | Un id de membre venant de [`GET /team/members`](/api-reference/operations/listteammembers/), ou `null` pour retirer le propriétaire. Id inconnu : `422`. |
| `next_action_at` | Date ISO 8601, ou `null`. |
| `next_action_label` | 80 caractères maximum, ou `null`. Exige une date `next_action_at` (422 sinon). Effacer la date efface le libellé. |
| `deal_status` | `open`, `won` ou `lost`. |
| `lost_reason` | Une valeur parmi `price`, `timing`, `unqualified`, `competitor`, `unreachable`, `other`. Obligatoire avec `deal_status: "lost"`, effacée pour `open` et `won`. |

Chaque changement écrit le journal du lead, les mêmes événements que le dashboard (`owner`, `next_action`, `outcome`), avec le nom de ta clé API comme acteur.

### `tags` et les étiquettes de l'agent

Quand l'agent du lead a ses étiquettes allumées, il pose lui-même certaines
étiquettes (vois [Étiquettes de l'agent](/fr/dashboard/labels/)). `tags` les
contient avec celles posées par des personnes. Un `PATCH` avec `tags` compte
comme un changement à la main, comme dans le dashboard :

- retirer une des étiquettes de l'agent, ou ajouter une de ses étiquettes, passe les étiquettes de ce lead aux personnes : l'agent ne les change plus. Rends-les-lui dans le dashboard avec **Rendre la main à l'agent** ;
- une étiquette à toi, comme `"VIP"`, ne change rien pour l'agent ;
- le nom d'une des étiquettes de l'agent est enregistré avec l'orthographe de l'agent, quelle que soit la casse envoyée. Avec **Une étiquette principale**, l'étiquette principale que tu ajoutes remplace la précédente du lead.

Si les réglages des étiquettes de l'agent ne peuvent pas être lus, l'appel
répond `503 tag_rules_unavailable` et rien n'est écrit : réessaie dans un
instant.

## Notes

Les notes sont les textes libres que ton équipe voit sur la fiche du 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":"Rappelé, veut un devis avant vendredi."}'
```

**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: 'Rappelé, veut un devis avant vendredi.' }),
});
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": "Rappelé, veut un devis avant vendredi."},
)
note = r.json()["data"]
```

```json
{
  "data": {
    "id": "66f1a2b3c4d5e6f7a8b9c0e2",
    "text": "Rappelé, veut un devis avant vendredi.",
    "author": "API · Mon CRM",
    "created_at": "2026-09-19T08:12:00.000Z"
  }
}
```

`text` fait 1 à 2000 caractères. L'auteur est `API · <nom de la clé>` pour les notes que tu crées, ou le nom du coéquipier pour les notes écrites dans le dashboard. `GET /leads/{id}/notes` renvoie `{ "data": [ ...notes ] }`, les plus récentes d'abord, 100 maximum.

## Passer une conversation à un humain, puis la rendre

`POST /leads/{id}/handoff` arrête l'agent IA sur ce lead. Il reste silencieux jusqu'à ce que tu appelles `POST /leads/{id}/resume`. C'est le même interrupteur que la prise en main du dashboard, les deux ne peuvent jamais se contredire.

**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"
  }
}
```

- Le `status` du lead est préservé : prendre la main ne marque jamais un lead comme arrêté ou qualifié.
- Les deux appels sont idempotents : un deuxième handoff sur un lead déjà pris en main répond `200`.
- `dashboard_synced: false` signifie que l'agent est bien arrêté mais que la liste Leads peut avoir un temps de retard. La vue conversation est toujours juste.
- La règle de statut : handoff et resume ne s'appliquent qu'aux leads déjà engagés par l'agent (`in_progress`, `stopped`, `cold`, `qualified`, `not_interested`). Un lead `queued` ou `pending` n'a pas de conversation à passer et répond `409 invalid_state`.
- Sur Instagram et Messenger, l'interrupteur est écrit sur le lead lui-même, là où leurs moteurs le lisent, exactement comme **Prendre la main** dans le dashboard. `resume` met aussi fin à la pause ouverte par la réponse d'une personne (`agent_paused_until` sur [`GET /conversations`](/fr/developers/guides/conversations/)).

> **Envoyer pendant que l'agent est arrêté**
Après un handoff, tes propres messages passent par [`POST /messages`](/fr/developers/guides/messages/). L'agent ne répondra pas au lead tant que tu ne l'as pas réactivé.

## Le champ stage

`stage` est en lecture seule et dérivé du lead exactement comme le funnel du dashboard. Il répond « où en est cette personne commercialement ? » en un mot, alors que `status` est le vocabulaire propre à l'IA.

| `stage` | Quand |
|---|---|
| `contacted` | Pas encore de réponse comptée, et pas `cold` : par exemple une personne qui a écrit en premier et n'a pas encore eu de réponse. |
| `conversation` | Le lead a répondu, l'IA ou un humain lui parle. |
| `waiting` | Pas encore contacté : le premier message a été retenu et n'est jamais parti (`status: pending`). |
| `qualified` | Intérêt validé (`status: qualified`). |
| `booked` | Un rendez-vous est au calendrier, ou a eu lieu. L'emporte sur toutes les autres valeurs. |
| `not_interested` | Mauvaise cible ou refus. |
| `cold` | L'agent a écrit en premier, pas encore de réponse (`status: cold`). |
| `stopped` | La conversation a été arrêtée. |

## Relier à ton CRM

Envoie l'identifiant de ta propre fiche dans `external_reference` quand tu pousses un lead opt-in avec [`POST /campaigns/{id}/leads`](/fr/developers/guides/campaigns/). WhatSetter le stocke tel quel, le renvoie sur chaque lead et chaque webhook, et te laisse le retrouver :

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

`external_reference` vaut `null` pour les leads qui ne viennent pas de toi (imports CSV, imports de liste, formulaires de page de vente). Pour ceux-là, compare sur `phone` : chiffres seuls des deux côtés.

## Les erreurs que tu rencontreras

| HTTP | `code` | Quand |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Clé absente, inconnue ou révoquée. |
| 403 | `insufficient_scope` | La clé n'a pas `leads:read` ou `leads:write`. |
| 404 | `not_found` | Lead inconnu, ou lead d'un autre espace de travail. |
| 409 | `invalid_state` | Handoff ou resume sur un lead jamais contacté. |
| 422 | `validation_error` | Statut inconnu, téléphone invalide, id de membre inconnu, corps vide, curseur invalide ou expiré. |
| 503 | `tag_rules_unavailable` | Un changement de `tags` alors que les réglages des étiquettes de l'agent n'ont pas pu être lus. Rien n'a été écrit. Tu peux réessayer. |
| 429 | `rate_limited` | Trop de requêtes cette minute. Respecte `Retry-After`. |
| 502 | `upstream_error` | Le workflow de contrôle de l'agent était injoignable. Tu peux réessayer. |

## Voir aussi

- [Campagnes : pousser un lead opt-in](/fr/developers/guides/campaigns/)
- [Messages : écrire à un lead](/fr/developers/guides/messages/)
- [Leads dans le dashboard](/fr/dashboard/leads/)
- [Webhooks signés](/fr/developers/webhooks/)
