# Campaign API

Run [auto dialer](/auto-dialer) campaigns from your CRM or backend: create a campaign on one of your agent groups, add phone numbers, start / pause / stop it, and read the result of every call.

When a campaign runs, the dialer places **one call per free agent** in the group: the customer and the agent are rung at the same time and connected once both have answered. A number that is not answered, busy, or fails — or is answered when no agent picked up in time — is called again 5 minutes later, up to 3 attempts in all. Every call is recorded.

Requires a Bearer API token (from [Authentication](/api-docs/authentication) / dashboard **API Tokens**) and the **call-center** permission.

Rate limit: 60 requests per minute per account, shared by all Campaign API endpoints.

## Flow

1. [List Groups](/api-docs/campaigns/groups) — pick the agent group. Its agents take the calls; its number is the caller ID.
2. [Create Campaign](/api-docs/campaigns/create) — with numbers, or empty. It starts as `draft`.
3. [Add Numbers](/api-docs/campaigns/add-numbers) — up to 1,000 per request, any time before the campaign is final.
4. [Start](/api-docs/campaigns/actions) the campaign.
5. Poll [Call Results](/api-docs/campaigns/calls) for new rows and [Get Campaign](/api-docs/campaigns/get) for progress until `status` is `completed`.

## Endpoints

| Method | Path | Page |
| --- | --- | --- |
| GET | `/api/cc/groups` | [List Groups](/api-docs/campaigns/groups) |
| POST | `/api/cc/campaigns` | [Create Campaign](/api-docs/campaigns/create) |
| GET | `/api/cc/campaigns` | [List Campaigns](/api-docs/campaigns/list) |
| GET | `/api/cc/campaigns/:id` | [Get Campaign](/api-docs/campaigns/get) |
| POST | `/api/cc/campaigns/:id/contacts` | [Add Numbers](/api-docs/campaigns/add-numbers) |
| POST | `/api/cc/campaigns/:id/start` · `/pause` · `/stop` | [Start, Pause, Stop](/api-docs/campaigns/actions) |
| GET | `/api/cc/campaigns/:id/calls` | [Call Results](/api-docs/campaigns/calls) |
| GET | `/api/cc/campaigns/:id/contacts` | [List Numbers](/api-docs/campaigns/numbers) |

## Statuses

| Status | Meaning |
| --- | --- |
| `draft` | Created, never started |
| `running` | Calling |
| `paused` | No new calls; calls in progress finish. Start it again to continue |
| `stopped` | Final. No new calls or numbers; numbers not called yet become `cancelled` |
| `completed` | Final. Every number is done or out of attempts |

| Action | Allowed from |
| --- | --- |
| start | `draft`, `paused` |
| pause | `running` |
| stop | `draft`, `running`, `paused` |
| add numbers | `draft`, `running`, `paused` |

Only one campaign can run on a group at a time.

## Errors

Campaign API errors return a message for people and a `code` for your code:

```json
{
  "error": "Another campaign is running on this group. Pause or stop it first.",
  "code": "queue_busy"
}
```

Validation errors return `422` with an `errors` array instead.

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | — | Missing or invalid access token |
| 403 | — | Account does not have the call-center permission |
| 404 | `campaign_not_found` | Unknown campaign, or not on your account |
| 409 | `invalid_status` | The action is not allowed in the campaign's status |
| 409 | `no_contacts` | Start needs at least one number not called yet |
| 409 | `queue_busy` | Another campaign is running on this group |
| 409 | `sender_has_no_trunk` | The group's number cannot place calls; contact support |
| 409 | `campaign_stopped` · `campaign_completed` | The campaign is already final |
| 409 | `duplicate_request` | The same `request_id` was used within 15 minutes |
| 422 | `group_not_eligible` | The group is not approved or has no number |
| 422 | `no_valid_numbers` | None of the numbers is a valid Bangladesh mobile number |
| 422 | `invalid_campaign` | The call engine refused the campaign settings |
| 429 | — | Rate limit exceeded |
| 503 | `engine_unreachable` | The call engine could not be reached; try again |

Phone numbers must be Bangladesh mobile numbers (`01XXXXXXXXX`, `+8801XXXXXXXXX` and `8801XXXXXXXXX` are accepted). Times are ISO 8601 with the `Asia/Dhaka` offset.