# List leads

`GET https://app.whatsetter.com/api/v1/leads`

Leads of the workspace, most recently active first.

Like the dashboard, the listing leaves out the participants of
group-purpose campaigns (`purpose: group` in `GET /campaigns`) unless
you filter on that `campaign_id` explicitly. Requires scope
`leads:read`.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `status` | query | qualified \| in_progress \| not_interested \| cold \| pending \| stopped \| queued | no | Filter by status. |
| `campaign_id` | query | string | no | Filter by campaign. Accepts the campaign's `campaign_id` slug or its document `id` (both returned by `GET /campaigns`). |
| `phone` | query | string | no | Exact lookup by phone (international format, e.g. `+33612345678`). |
| `external_reference` | query | string | no | Exact lookup by the id you sent on `POST /campaigns/{id}/leads`. The supported way to resolve "which WhatSetter lead is my record #4471?". |
| `channel` | query | whatsapp \| instagram \| facebook | no | Only leads reached on this channel: `whatsapp`, `instagram` (Instagram DMs) or `facebook` (Messenger, through a Facebook Page). `whatsapp` also returns the leads created before the channel was recorded. |
| `since` | query | string | no | Only leads active after this ISO-8601 date (on `last_message_at`). |
| `source` | query | instagram \| facebook \| tiktok \| youtube \| linkedin \| x \| snapchat \| pinterest \| google \| website \| email \| sms \| qr \| ads \| other \| direct \| list \| api \| webhook \| inbound \| manual \| messenger | no | Where the lead came from (see the `source` field). Exact match on the stored value — leads created before origins were recorded stay out of a filtered listing. |
| `tracked_link_id` | query | string | no | Only leads brought by this tracked WhatsApp link (Dashboard → Liens). |
| `limit` | query | integer | no |  |
| `cursor` | query | string | no | Opaque cursor from the previous page's `pagination.next_cursor`. |

## Example request

```bash
curl --request GET \
  --url 'https://app.whatsetter.com/api/v1/leads' \
  --header 'Authorization: Bearer ws_live_…'
```

## Responses

### 200: Page of leads

```json
{
  "data": [
    {
      "id": "",
      "phone": "",
      "whatsapp_id": "",
      "name": "",
      "status": "qualified",
      "qualified": false,
      "qualified_at": "",
      "replied": false,
      "campaign_id": "",
      "list_id": "",
      "source": "instagram",
      "source_confidence": "certain",
      "tracked_link_id": "",
      "external_reference": "",
      "channel": "whatsapp",
      "ig_username": "",
      "email": "",
      "tags": [
        ""
      ],
      "messages_count": 0,
      "booking_status": "",
      "assigned_to": "",
      "stage": "contacted",
      "deal_status": "open",
      "lost_reason": "price",
      "next_action_at": "",
      "next_action_label": "",
      "first_contact_at": "",
      "last_message_at": "",
      "last_message_direction": "inbound",
      "created_at": "",
      "updated_at": ""
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": ""
  }
}
```

### 401: Missing, unknown or revoked API key

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 403: The key lacks the required scope (`insufficient_scope`), the plan does not have this part of the API (`not_in_plan`), or Instagram is not enabled on the workspace (`instagram_not_enabled`, Instagram routes)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 422: Invalid parameter or body (also an invalid or expired `cursor`)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```


Source: https://docs.whatsetter.com/api-reference/operations/listleads/
