# Leads

> List, filter and update your leads, add notes, hand a conversation to a human and match every lead with your CRM records.

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

A lead is one person your AI setter talks to. The API exposes the same record as the **Leads** tab of the dashboard: stage (`status`), labels (`tags`), owner, next action, deal outcome and notes.

## Endpoints

| Method | Path | 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` |

## What changes what the agent does

A lead carries a stage (`status`) and labels (`tags`). Only the stage drives
the agent.

| Field | Effect on the agent |
|---|---|
| `status` | The stage the agent works from. It sets it itself, from what its prompt says, and it respects a stage set by a person or by your tools: `qualified`, it stops qualifying; `not_interested` and `stopped`, it no longer writes; `cold`, it stops insisting; `in_progress`, it resumes. |
| `tags` | None. A label never stops the agent, never qualifies a lead and never makes it offer a meeting. Labels are for sorting: filters, the export, notifications, follow-ups limited to some labels, your CRM. |
| `handoff`, `resume` | Stop the agent on this lead, then let it answer again. See below. |

A label named like a stage, for example `"qualified"` in `tags`, does not
qualify the lead: send `"status": "qualified"`. To change when the agent
qualifies leads on its own, edit its prompt: see
[Deciding when a lead is qualified](/dashboard/prompt/#deciding-when-a-lead-is-qualified).

## List and filter leads

Leads come back most recently active first, 25 per page by default.

**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": "Call back",
      "created_at": "2026-09-10T07:59:58.000Z",
      "updated_at": "2026-09-18T16:42:05.000Z"
    }
  ],
  "pagination": { "has_more": true, "next_cursor": "66f1a2b3c4d5e6f7a8b9c0d1" }
}
```

`phone` is digits only, without the `+`. Pass `cursor=next_cursor` to get the next page.

### Filters

| Parameter | What it does |
|---|---|
| `status` | One of the statuses below. `qualified` returns every lead that was qualified at some point (its qualification date is set). |
| `campaign_id` | The campaign's `campaign_id` slug or its `id`, both from [`GET /campaigns`](/api-reference/operations/listcampaigns/). |
| `phone` | Exact lookup, international format (`+33612345678`). |
| `external_reference` | Exact lookup on the id you sent with `POST /campaigns/{id}/leads`. |
| `source` | Where the lead came from: `instagram`, `facebook`, `tiktok`, `youtube`, `linkedin`, `x`, `snapchat`, `pinterest`, `google`, `website`, `email`, `sms`, `qr`, `ads`, `other`, `direct`, `list`, `api`, `webhook`, `inbound`, `manual`, `messenger` (wrote to a Facebook Page on Messenger). |
| `tracked_link_id` | Only leads brought by this [tracked link](/developers/guides/links/). |
| `channel` | `whatsapp`, `instagram` or `facebook` (Messenger, through a Facebook Page). |
| `since` | Only leads active after this ISO 8601 date (on `last_message_at`). |
| `limit`, `cursor` | Pagination, 1 to 100 per page. |

> **Group campaigns stay out**
Without a `campaign_id` filter, leads of group-purpose campaigns (group participants) are not listed, same as the dashboard. Pass the group campaign's id to see them.

### Status values

| `status` | Meaning |
|---|---|
| `queued` | Imported, waiting for its first message. |
| `pending` | Not contacted yet: the lead's first message was held back and never left. There is no conversation, and nobody is asked to act. |
| `in_progress` | The conversation is underway. |
| `qualified` | The agent validated interest, or you set it from the API. |
| `not_interested` | Wrong fit or explicit refusal. |
| `cold` | The agent wrote first and the lead has not replied yet. At the lead's first reply, it becomes `in_progress`. Also set when a person marks the lead unanswered. |
| `stopped` | The conversation was stopped. |
| `unknown` | An internal value the public API does not name. |

## Get one 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"]
```

The response is `{ "data": lead }` with the same object as above. A lead of another workspace answers `404`, never `403`.

## Update a lead

Send only the fields you change. At least one is required.

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

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

The response is the updated lead, `200`.

| Field | Rules |
|---|---|
| `status` | `qualified`, `in_progress`, `not_interested`, `cold`, `pending`, `stopped` or `queued`. Setting `qualified` stamps `qualified_at` once. |
| `tags` | Array of up to 20 strings, 40 characters each. Replaces the whole list. Empty or too long tags are dropped, duplicates removed. Never changes what the agent does: see the agent's labels below. |
| `assigned_to` | A member id from [`GET /team/members`](/api-reference/operations/listteammembers/), or `null` to unassign. Unknown id: `422`. |
| `next_action_at` | ISO 8601 date, or `null`. |
| `next_action_label` | Up to 80 characters, or `null`. Needs a `next_action_at` date (422 otherwise). Clearing the date clears the label. |
| `deal_status` | `open`, `won` or `lost`. |
| `lost_reason` | One of `price`, `timing`, `unqualified`, `competitor`, `unreachable`, `other`. Required with `deal_status: "lost"`, cleared for `open` and `won`. |

Every change writes the lead's journal, the same events the dashboard writes (`owner`, `next_action`, `outcome`), with your API key's name as the actor.

### `tags` and the agent's labels

When the lead's agent has its labels on, the agent puts some labels itself
(see [Agent labels](/dashboard/labels/)). `tags` holds them together with
the ones people put. A `PATCH` with `tags` counts as a change by hand, as in
the dashboard:

- taking off one of the agent's labels, or adding one of its labels, hands this lead's labels over to people: the agent stops changing them. Give them back in the dashboard with **Hand back to the agent**;
- a label of your own, such as `"VIP"`, changes nothing for the agent;
- a name of one of the agent's labels is stored with the agent's spelling, whatever case you send. With **One main label**, the main label you add replaces the lead's previous one.

If the agent's label settings cannot be read, the call answers
`503 tag_rules_unavailable` and nothing is written: try again in a moment.

## Notes

Notes are the free-text entries your team sees on the lead's record.

**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":"Called back, wants a quote before Friday."}'
```

**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: 'Called back, wants a quote before Friday.' }),
});
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": "Called back, wants a quote before Friday."},
)
note = r.json()["data"]
```

```json
{
  "data": {
    "id": "66f1a2b3c4d5e6f7a8b9c0e2",
    "text": "Called back, wants a quote before Friday.",
    "author": "API · My CRM",
    "created_at": "2026-09-19T08:12:00.000Z"
  }
}
```

`text` is 1 to 2000 characters. The author is `API · <key name>` for notes you create, or the teammate's name for notes written in the dashboard. `GET /leads/{id}/notes` returns `{ "data": [ ...notes ] }`, newest first, up to 100.

## Hand a conversation to a human, then give it back

`POST /leads/{id}/handoff` stops the AI agent on this lead. It stays silent until you call `POST /leads/{id}/resume`. This is the same switch as the dashboard's take-over toggle, so the two never disagree.

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

- The lead's `status` is preserved: handing over never marks a lead as stopped or qualified.
- Both calls are idempotent: a second handoff on a lead already handed over answers `200`.
- `dashboard_synced: false` means the agent is stopped but the Leads list may lag. The conversation view is always right.
- The status rule: handoff and resume only apply to leads the agent has already engaged (`in_progress`, `stopped`, `cold`, `qualified`, `not_interested`). A `queued` or `pending` lead has no conversation to hand over and answers `409 invalid_state`.
- On Instagram and Messenger the switch is written on the lead itself, where their engines read it, exactly like the dashboard's **Take over**. `resume` also ends the pause a person's reply opened (`agent_paused_until` on [`GET /conversations`](/developers/guides/conversations/)).

> **Sending while the agent is stopped**
After a handoff, your own messages go through [`POST /messages`](/developers/guides/messages/). The agent will not answer the lead until you resume it.

## The stage field

`stage` is read-only and derived from the lead exactly like the dashboard's funnel. It answers "where is this person commercially?" in one word, while `status` is the AI's own vocabulary.

| `stage` | When |
|---|---|
| `contacted` | No reply counted yet, and not `cold`: for example a person who wrote first and is not answered yet. |
| `conversation` | The lead replied, the AI or a human is talking. |
| `waiting` | Not contacted yet: the first message was held back and never left (`status: pending`). |
| `qualified` | Interest validated (`status: qualified`). |
| `booked` | A meeting is on the calendar, or was held. Wins over every other value. |
| `not_interested` | Wrong fit or refusal. |
| `cold` | The agent wrote first, no answer yet (`status: cold`). |
| `stopped` | The conversation was stopped. |

## Correlate with your CRM

Send your own record id as `external_reference` when you push an opt-in lead with [`POST /campaigns/{id}/leads`](/developers/guides/campaigns/). WhatSetter stores it verbatim, returns it on every lead and every webhook, and lets you look it up:

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

`external_reference` is `null` for leads that did not come from you (CSV imports, list imports, sales-page forms). For those, match on `phone`: digits only on both sides.

## Errors you will meet

| HTTP | `code` | When |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Key absent, unknown or revoked. |
| 403 | `insufficient_scope` | The key lacks `leads:read` or `leads:write`. |
| 404 | `not_found` | Unknown lead, or a lead of another workspace. |
| 409 | `invalid_state` | Handoff or resume on a lead that was never contacted. |
| 422 | `validation_error` | Unknown status, bad phone, unknown member id, empty body, invalid or expired cursor. |
| 503 | `tag_rules_unavailable` | A `tags` change while the agent's label settings could not be read. Nothing was written. Safe to retry. |
| 429 | `rate_limited` | Too many requests this minute. Honor `Retry-After`. |
| 502 | `upstream_error` | The agent-control workflow was unreachable. Safe to retry. |

## Related

- [Campaigns: push an opt-in lead](/developers/guides/campaigns/)
- [Messages: write to a lead](/developers/guides/messages/)
- [Leads in the dashboard](/dashboard/leads/)
- [Signed webhooks](/developers/webhooks/)
