> ## Documentation Index
> Fetch the complete documentation index at: https://docs.60db.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Campaign Recipients

> Add more people to a campaign that is scheduled, running, paused or completed

Add recipients to an existing campaign, as many times as you like. Send a CSV, or a JSON list from your own system (for example new leads from your CRM). New numbers are called after the ones already waiting, with the campaign's agent, phone line, calling windows, retries and variable mapping.

* **Scheduled, running and paused** campaigns take the new numbers as they are. A paused campaign stays paused.
* A **completed** campaign restarts to call them: it goes back to `running`, or `scheduled` when its start time is still ahead. It only restarts when at least one new number is added.
* A **cancelled** campaign is refused with `409`.
* A number the campaign already has is left as it is: it is not called again and its status does not change. It is counted in `already_in_campaign`.
* Numbers on your [do-not-call list](https://docs.60db.ai/features/agents-campaigns.md#do-not-call) and invalid rows are stored as skipped, as at create.

Use [Preview campaign add](https://docs.60db.ai/api-reference/agents/preview-campaign-add.md) first to see what a file would do.

## Request

### Headers

**Authorization** `string` *required*

Bearer token with your API key (scope `agents`)

**Content-Type** `string` *required*

application/json

**Idempotency-Key** `string`

1 to 128 printable characters without spaces. Send the same key again with the same body and you get the first result back, without anything being added twice. The same key with a different body is refused with `409`. Keys are per campaign

### Path

**campaignId** `string` *required*

The campaign `id`

### Body

Send exactly one of `csv_text` or `recipients`.

**csv\_text** `string`

A CSV in the same format as at create. Up to 5 MB and 20,000 rows. See [CSV format](https://docs.60db.ai/features/agents-campaigns.md#csv-format)

**recipients** `object[]`

1 to 20,000 people.

**properties**

**phone** `string` *required*

The phone number. A number without `+` gets the phone line's default country code

**variables** `object`

Up to 50 values for the agent's `{{variables}}`, by name, the same as CSV columns. Values are text, up to 500 characters each

The campaign's [variable mapping and defaults](https://docs.60db.ai/features/agents-campaigns.md#variables) apply to the new rows. A column the campaign maps does not have to be in a later file: its default is used.

## Response

**201 Created** (or **200 OK** when an `Idempotency-Key` replays the first result)

```json theme={null}
{
  "success": true,
  "data": {
    "batch_id": "1d1b7c1e-1b1d-4a5e-9a3b-6f4b0c2d9e10",
    "added": 2,
    "already_in_campaign": 1,
    "dnc": 1,
    "invalid_count": 1,
    "invalid": [{ "row": 5, "value": "n/a", "reason": "invalid_number" }],
    "duplicates": 0,
    "campaign": { "id": "…", "status": "running", "counts": { "total": 12, "pending": 6 } }
  }
}
```

| Field | Meaning |
| - | - |
| `batch_id` | The id of this add |
| `added` | New numbers that will be called |
| `already_in_campaign` | Numbers the campaign already had. They are left as they are |
| `dnc` | New numbers on your do-not-call list. Stored as skipped |
| `invalid_count`, `invalid` | Rows that cannot be used, stored as skipped. `reason` is `invalid_number` or `variables_too_large`. `invalid` holds up to 200 rows; `row` is the row (or list position) in what you sent |
| `duplicates` | Numbers listed more than once in what you sent. Each is kept once |
| `campaign` | The campaign after the add, as in [Get campaign](https://docs.60db.ai/api-reference/agents/get-campaign.md) |

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | `VALIDATION_ERROR` | Neither or both of `csv_text` and `recipients`, a list that is empty or longer than 20,000, a CSV larger than 5 MB, or a bad `Idempotency-Key` |
| 400 | `CAMPAIGN_INVALID` | The CSV cannot be used, for example it has no phone column. `field` is `csv_text` |
| 403 | `POLICY_DENY` | Your role cannot place calls, your plan is not active, or the API key lacks the `agents` scope |
| 404 | `CAMPAIGN_NOT_FOUND` | No campaign with this id in your workspace |
| 409 | `CAMPAIGN_NOT_EDITABLE` | The campaign was cancelled |
| 409 | `AGENT_NOT_FOUND` | The campaign's agent was deleted |
| 409 | `LINE_NOT_READY` | The campaign's phone line is not ready |
| 409 | `IDEMPOTENCY_CONFLICT` | This `Idempotency-Key` was already used for different recipients |
| 429 | `RATE_LIMITED` | Too many adds in the last minute (the same limit as creating campaigns). Send many people per request instead of one at a time |

## Example

```bash cURL (JSON list) theme={null}
curl -X POST https://api.60db.ai/agents/campaigns/CAMPAIGN_ID/recipients \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-leads-2026-11-18-0930" \
  -d '{
    "recipients": [
      { "phone": "+919876543210", "variables": { "name": "Asha", "city": "Pune" } },
      { "phone": "9876543211", "variables": { "name": "Ravi" } }
    ]
  }'
```

```bash cURL (CSV) theme={null}
curl -X POST https://api.60db.ai/agents/campaigns/CAMPAIGN_ID/recipients \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "csv_text": "phone_number,name\n+919876543212,Meera\n" }'
```

```javascript JavaScript theme={null}
const res = await fetch(`https://api.60db.ai/agents/campaigns/${campaignId}/recipients`, {
  method: "POST",
  headers: {
    Authorization: "Bearer your-api-key",
    "Content-Type": "application/json",
    "Idempotency-Key": `crm-${batchId}`,
  },
  body: JSON.stringify({ recipients: leads.map((l) => ({ phone: l.phone, variables: { name: l.name } })) }),
});
const { data } = await res.json();
console.log(`Added ${data.added}, already in campaign ${data.already_in_campaign}`);
```

```python Python theme={null}
import requests

res = requests.post(
    f"https://api.60db.ai/agents/campaigns/{campaign_id}/recipients",
    headers={"Authorization": "Bearer your-api-key", "Idempotency-Key": f"crm-{batch_id}"},
    json={"recipients": [{"phone": l["phone"], "variables": {"name": l["name"]}} for l in leads]},
)
data = res.json()["data"]
print(f"Added {data['added']}, already in campaign {data['already_in_campaign']}")
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.