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

# Campaigns

> Step 2. Send candidates for an enrichment. Record contacts them.

A campaign sends your candidates (name + mobile number) to an enrichment. Record contacts them on WhatsApp, follows up by call and SMS, and asks the enrichment's questions.

| Needs | You get | Scope |
| - | - | - |
| `enrichment_id` from [step 1](https://docs.userecord.io/enrichment-api/guides/enrichments.md) | `campaign_id` | `enrichment:campaigns` (reads also allow `enrichment:read`) |

> [!WARNING]
>
> **This contacts real people and spends credits.** Credits are charged **per candidate added** (the live wallet for a live key, the test wallet for a TEST key) and checked for the whole batch first: if your organisation cannot cover it, nothing is created and the call answers `402 INSUFFICIENT_CREDITS`. There is no separate start step: contacting begins as soon as the campaign is created. The phone numbers in the samples are placeholders, so replace them with your own test numbers. If the enrichment's `questions_status` is not yet `ready`, the campaign waits and goes out by itself.

## Candidates

* `phone_number` is an Indian mobile number: 10 digits (`98765 43210`) or with the country code (`+91 98765 43210`). It is returned in full as `+91…`.
* `external_id` is your id for the candidate. It comes back on every candidate and result.
* Up to 1,000 candidates per call.
* **A row that cannot be contacted never fails the call.** It is left out and listed in `skipped` with its position and a reason: `invalid_phone`, `opted_out` (the number replied STOP earlier) or `duplicate` (already earlier in the same list). If no row can be contacted, the call answers `400` and `details` say why for each one.
* **Daily allowance:** a key may put **2,000 different people** into campaigns a day (**200** for a TEST key), counted together with its Blue Collar campaigns and reset at midnight IST. A call that would go past it is refused whole with `429 DAILY_CAP` and creates nothing. Skipped rows do not count.
* A TEST key holds at most 50 candidates per enrichment (`403 FORBIDDEN` beyond that).

## Campaign status

| Status | Meaning |
| - | - |
| `sent` | Live. Candidates are being contacted. |
| `paused` | Paused by you. Nothing more goes out. |
| `completed` | Finished. |
| `cancelled` | Stopped for good. |

`awaiting_questions: true` means the questions are still being prepared and nothing has gone out yet.

## Endpoints

### Create a campaign

`POST /enrichments/{enrichment_id}/campaigns`

Returns `campaign_id`, the candidates and the skipped rows.

**Scope:** `enrichment:campaigns` · **Idempotency-Key:** required

> [!WARNING]
>
> This contacts real people.

| Field | Type | Description |
| - | - | - |
| `name` | `string` | **Required.** 1–200 characters. |
| `candidates` | `array<object>` | **Required.** 1–1,000 of `{ name, phone_number, external_id? }`. |
| `language` | `string` | Invite language. Defaults to the enrichment's schedule language. |

```javascript JavaScript theme={null}
const res = await call("POST", `/api/v1/partner/enrichments/${enrichmentId}/campaigns`, {
  name: "November talent pool",
  candidates: [
    { name: "Ravi Kumar", phone_number: "98765 43210", external_id: "cand-1001" },
    { name: "Meena S", phone_number: "91234 56780", external_id: "cand-1002" },
    { name: "Test Number", phone_number: "0000000000" },
  ],
});
const { data } = await res.json();
```

```python Python theme={null}
res = call("POST", f"/api/v1/partner/enrichments/{enrichment_id}/campaigns", {
    "name": "November talent pool",
    "candidates": [
        {"name": "Ravi Kumar", "phone_number": "98765 43210", "external_id": "cand-1001"},
        {"name": "Meena S", "phone_number": "91234 56780", "external_id": "cand-1002"},
        {"name": "Test Number", "phone_number": "0000000000"},
    ],
})
data = res.json()["data"]
```

```json Response · 201 theme={null}
{
  "success": true,
  "data": {
    "campaign": {
      "campaign_id": "EC_261121095438377TFUX07WN2XT42V",
      "enrichment_id": "WF_EN_261121094822026AEDRUB86TQVSML",
      "name": "November talent pool",
      "language": "english",
      "status": "sent",
      "awaiting_questions": true,
      "question_count": 2,
      "channels": { "whatsapp": true, "voice_call": true, "sms": true },
      "rejected_count": 1,
      "counts": { "candidates": 2, "sent": 0, "completed": 0 }
    },
    "candidates": [
      { "candidate_id": "6f1d2c3e-8a4b-4c57-9d10-2b7e5a9c1f33", "external_id": "cand-1001", "name": "Ravi Kumar", "phone_number": "+919876543210" },
      { "candidate_id": "0c9b7e21-5d3f-4a68-b1e4-77a2c8d9e054", "external_id": "cand-1002", "name": "Meena S", "phone_number": "+919123456780" }
    ],
    "skipped": [
      { "index": 2, "name": "Test Number", "phone_number": "0000000000", "reason": "invalid_phone" }
    ]
  }
}
```

**Errors:** `400 VALIDATION_FAILED` (no contactable number, or a field wrong), `402 INSUFFICIENT_CREDITS` (the organisation's credits do not cover the whole batch; nothing is created), `403 FORBIDDEN` (the TEST limit), `404 NOT_FOUND` (no such enrichment, or it is archived), `429 DAILY_CAP` (the key's daily allowance of different people is used up).

### List campaigns

`GET /enrichments/{enrichment_id}/campaigns`

The campaigns of an enrichment, newest first, with `counts` of candidates, sent and completed. Takes `limit` and `cursor`.

**Scope:** `enrichment:read`

### Get a campaign

`GET /enrichments/{enrichment_id}/campaigns/{campaign_id}`

Progress of one campaign: the funnel, numbers per channel and where candidates drop off per question.

**Scope:** `enrichment:read`

```json Response · 200 theme={null}
{
  "success": true,
  "data": {
    "campaign_id": "EC_261121095438377TFUX07WN2XT42V",
    "enrichment_id": "WF_EN_261121094822026AEDRUB86TQVSML",
    "kpis": {
      "uploaded": 3, "rejected": 1, "sent": 2,
      "sent_by": { "whatsapp": 2, "sms": 0, "call": 1 },
      "link_opened": 1, "completed": 1, "opted_out": 0, "failed": 0
    },
    "drop_off": {
      "started": 1,
      "questions": [
        { "order": 0, "question_text": "Are you open to a new job right now?", "answered": 1 },
        { "order": 1, "question_text": "Tell us about the work you do and where you want to work.", "answered": 1 }
      ]
    }
  }
}
```

### Pause a campaign

`POST /enrichments/{enrichment_id}/campaigns/{campaign_id}/pause`

Nothing more goes out (no invite, follow-up, SMS or call) until you resume. Only a live campaign can be paused, and one whose candidates have all finished has nothing left to pause.

**Scope:** `enrichment:campaigns` · **Idempotency-Key:** optional · **Errors:** `404 NOT_FOUND`, `409 CONFLICT` (the campaign is not live, or every candidate has already finished)

### Resume a campaign

`POST /enrichments/{enrichment_id}/campaigns/{campaign_id}/resume`

Sending carries on where it stopped. Only a paused campaign can be resumed.

**Scope:** `enrichment:campaigns` · **Idempotency-Key:** optional · **Errors:** `404 NOT_FOUND`, `409 CONFLICT` (the campaign is not paused)


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