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

# Campaigns API

> Create, list, retrieve, and update outbound voice campaigns with fixed, per-contact, or pooled caller IDs.

A campaign links an agent to contacts and defines concurrency, caller-ID selection, scheduling, daily windows, and retry behavior.

<ParamField path="account_id" type="string" required>
  Your Vobiz account ID. Use the same value in `X-Auth-ID`.
</ParamField>

<ParamField header="X-Auth-ID" type="string" required>
  Your Vobiz account ID, for example `MA_XXXXXXXX`.
</ParamField>

## Endpoints

| Method | Path                                                                           | Description                            |
| ------ | ------------------------------------------------------------------------------ | -------------------------------------- |
| `POST` | `/api/v1/account/{account_id}/campaigns`                                       | Create a draft campaign.               |
| `GET`  | `/api/v1/account/{account_id}/campaigns`                                       | List active or archived campaigns.     |
| `GET`  | `/api/v1/account/{account_id}/campaigns/{campaign_id}`                         | Retrieve a campaign and its health.    |
| `PUT`  | `/api/v1/account/{account_id}/campaigns/{campaign_id}`                         | Update a `draft` or `ready` campaign.  |
| `GET`  | `/api/v1/account/{account_id}/campaigns/{campaign_id}/call-lookup/{call_uuid}` | Validate campaign ownership of a call. |

## Create a campaign

| Field                | Required    | Description                                                                                         |
| -------------------- | ----------- | --------------------------------------------------------------------------------------------------- |
| `name`               | Yes         | Campaign name. Maximum 100 characters.                                                              |
| `agent_id`           | Yes         | ID of an existing agent.                                                                            |
| `cps`                | No          | Retained for compatibility. Values below `1` normalize to `1`; CPS does not gate campaign capacity. |
| `max_concurrent`     | Yes         | At least `1` and no higher than the account concurrency limit.                                      |
| `timezone`           | Yes         | IANA timezone such as `Asia/Kolkata`.                                                               |
| `caller_id_strategy` | Yes         | `fixed`, `per_contact`, or `pool`.                                                                  |
| `fixed_caller_id`    | Conditional | Required for `fixed`. Use E.164 format.                                                             |
| `scheduled_at`       | No          | ISO 8601 timestamp for scheduler-based launch.                                                      |
| `window_enabled`     | No          | Enables the daily calling window.                                                                   |
| `window_start_time`  | Conditional | Required when the window is enabled. `HH:mm` format.                                                |
| `window_end_time`    | Conditional | Required when enabled and must differ from the start time.                                          |
| `retry_attempts`     | No          | Retries after the initial attempt. Range `0`–`5`.                                                   |
| `retry_delays`       | No          | Delay in minutes for each retry.                                                                    |
| `retry_window_days`  | No          | Maximum retry window. Defaults to `7`.                                                              |
| `notify_url`         | No          | Target for signed campaign and contact webhooks.                                                    |

### Fixed caller ID

```bash cURL theme={null}
curl -X POST \
  "https://campaign.vobiz.ai/api/v1/account/{account_id}/campaigns" \
  -H "X-Auth-ID: {account_id}" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Appointment Reminders",
    "agent_id": "{agent_id}",
    "cps": 3,
    "max_concurrent": 10,
    "timezone": "Asia/Kolkata",
    "caller_id_strategy": "fixed",
    "fixed_caller_id": "+919876543210",
    "window_enabled": true,
    "window_start_time": "09:00",
    "window_end_time": "18:00",
    "retry_attempts": 2,
    "retry_delays": [60, 240],
    "retry_window_days": 7,
    "notify_url": "https://example.com/campaign-webhooks"
  }'
```

The response is `201` with a `draft` campaign. Upload contacts to move it to `ready`.

## Caller-ID strategies

<Tabs>
  <Tab title="Fixed">
    Set `caller_id_strategy` to `fixed` and supply `fixed_caller_id`. Every attempt uses the same number.
  </Tab>

  <Tab title="Per contact">
    Set the strategy to `per_contact`. Every CSV row must contain a `from` value. Upload fails if the column is missing.
  </Tab>

  <Tab title="Pool">
    Set the strategy to `pool`, configure rotation and limits, then add numbers through the [caller pool endpoints](/docs/campaign-manager/caller-pool) before launch.

    `pool_rotation_strategy` accepts `round_robin`, `least_used`, or `random`. You can also set `pool_max_calls_per_number`, `pool_max_calls_per_day`, and `pool_cooldown_seconds`.
  </Tab>
</Tabs>

## List campaigns

Use `limit` and `offset` for pagination. Active campaigns are returned by default.

```http theme={null}
GET /api/v1/account/{account_id}/campaigns?limit=20&offset=0
GET /api/v1/account/{account_id}/campaigns?archived=true&limit=20&offset=0
```

Archived campaigns are read-only. Their contacts, CDRs, and statistics remain available.

## Retrieve health

The campaign response includes status, outcome counters, capacity settings, caller-ID strategy, schedule, daily window, pause reason, webhook URL, and timestamps.

For a running campaign, `health` is computed from recent dial activity:

* `active` — calls are being placed.
* `idle` — running but currently not dialing, for example while account capacity is saturated.
* `stalled` — no recent dial beyond the watchdog threshold.
* `not_started` — no dial has occurred.

## Update a campaign

You can update a campaign only while it is `draft` or `ready`. Every request field is optional. Use `clear_schedule: true` to remove an existing schedule. `max_concurrent` must remain within the account limit.