# Add an opt-in lead (sends their first message)

`POST https://app.whatsetter.com/api/v1/campaigns/{id}/leads`

The CRM primitive for **opt-in** leads: when someone signs up on your
client's funnel or CRM, push them here and WhatSetter runs the exact
same pipeline as the campaign's public sales-page webhook, with the
anti-ban protections applied automatically:

1. Phone validation and WhatsApp-registration check, deduplication
   against leads already contacted.
2. **Daily first-contact quota** and anti-bot pacing: over-quota leads
   are queued for the next window, never dropped.
3. The AI writes a **personalized first message** from the campaign's
   template, the lead's name, the source, and every key you pass in
   `additional_data` (budget, city, product of interest, plan...).
4. The lead lands in the campaign and the agent handles replies.

The pipeline is asynchronous, so the endpoint answers `202` as soon as
the lead is accepted. Follow progress with `GET /leads` (filter on
`campaign_id`) or the signed webhooks. Accepts the campaign document
`id` or its `campaign_id` slug in the path. Requires scope
`messages:send`.

### Correlating with your own records

Because the lead row is created *later* (after deduplication and
quota/pacing checks), the `202` cannot return a WhatSetter lead id —
there is none yet. Send your own id in **`external_reference`** instead.
We store it verbatim and echo it back as `contact.external_reference` on
every outbound webhook, so you can match our events to your records with
no phone-number join. You can also look it up any time with
`GET /leads?external_reference=...`.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Campaign document id, or its `campaign_id` slug. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `phone` | string | yes | International format, e.g. `+33612345678` (6 to 15 digits, `+`, spaces and dashes tolerated). |
| `name` | string | no |  |
| `email` | string | no |  |
| `source_url` | string | no | Where the lead came from (defaults to `api`). |
| `external_reference` | string | no | Your own id for this contact (CRM record id, row id...). Stored verbatim, never parsed, and echoed back as `contact.external_reference` on every webhook. This is the supported way to correlate our events with your records.  |
| `additional_data` | object | no | Free-form CRM fields (up to 30 keys, 2000 characters total). The AI uses them to personalize the first message. These are **not** stored and **not** returned — use `external_reference` for anything you need back. Keys that belong to the funnel itself are ignored inside `additional_data`: `phone`, `phone_raw`, `phone_formatted`, `phone_whatsapp`, `name`, `email`, `source_url`, `external_reference`, `team_slug`, `campaign_slug`, `state`, `headers`, `params`, `query`.  |

```json
{
  "phone": "+33612345678",
  "name": "Marie Dupont",
  "email": "marie@acme.fr",
  "source_url": "crm:hubspot",
  "external_reference": "4471",
  "additional_data": {
    "offre": "Pack Pro",
    "ville": "Lyon",
    "budget": "500-1000"
  }
}
```

## Example request

```bash
curl --request POST \
  --url 'https://app.whatsetter.com/api/v1/campaigns/{id}/leads' \
  --header 'Authorization: Bearer ws_live_…'
  --header 'Content-Type: application/json' \
  --data '{"phone":"+33612345678","name":"Marie Dupont","email":"marie@acme.fr","source_url":"crm:hubspot","external_reference":"4471","additional_data":{"offre":"Pack Pro","ville":"Lyon","budget":"500-1000"}}'
```

## Responses

### 202: Lead accepted into the first-contact pipeline

```json
{
  "data": {
    "status": "",
    "campaign_id": "",
    "phone": "",
    "external_reference": "",
    "note": ""
  }
}
```

### 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": ""
  }
}
```

### 404: Resource not found in this workspace

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

### 409: `invalid_state`: the campaign is not active (pause / draft /
archived), or it has never been opened in the dashboard and has no
funnel identifiers yet (open it once, or contact support).


```json
{
  "error": {
    "code": "invalid_state",
    "message": "Leads can only be pushed to an active campaign (current status: paused)."
  }
}
```

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

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

### 502: `upstream_error`: the first-message pipeline is unreachable or did not accept the lead. Safe to retry in a moment.

```json
{
  "error": {
    "code": "upstream_error",
    "message": "The first-message pipeline is unreachable. Try again in a moment."
  }
}
```


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