> ## 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.

# Campaign controls API

> Start, pause, resume, cancel, and archive outbound voice campaigns.

Campaign control endpoints use `POST` and do not require a request body.

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

<ParamField path="campaign_id" type="string" required>
  The campaign to start.
</ParamField>

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

| Action  | Endpoint                           | Allowed state                       | Result                                                 |
| ------- | ---------------------------------- | ----------------------------------- | ------------------------------------------------------ |
| Start   | `/campaigns/{campaign_id}/start`   | `ready`                             | Starts immediately and clears `scheduled_at`.          |
| Pause   | `/campaigns/{campaign_id}/pause`   | `running`                           | Stops new dials; in-flight calls finish.               |
| Resume  | `/campaigns/{campaign_id}/resume`  | `paused`                            | Returns to `running` and re-enqueues pending contacts. |
| Cancel  | `/campaigns/{campaign_id}/cancel`  | `running`, `paused`                 | Permanently stops remaining work.                      |
| Archive | `/campaigns/{campaign_id}/archive` | Any non-running, non-archived state | Soft-deletes the campaign while preserving data.       |

The full prefix is:

```text theme={null}
/api/v1/account/{account_id}/campaigns/{campaign_id}
```

## Start immediately

```bash cURL theme={null}
curl -X POST \
  "https://campaign.vobiz.ai/api/v1/account/{account_id}/campaigns/{campaign_id}/start" \
  -H "X-Auth-ID: {account_id}" \
  -H "X-Auth-Token: {auth_token}"
```

Account concurrency is enforced when each call is dialed. If the account is saturated, the campaign remains `running` but idle until capacity becomes available.

## Pause and resume

A manual pause sets `paused_reason` to `manual_pause` and sends `campaign.paused` when `notify_url` is configured. It requires an explicit resume.

Resuming immediately re-enqueues pending contacts and sends `campaign.resumed`.

## Cancel and archive

Cancellation is permanent. No further contacts are dialed, and the campaign cannot be restarted. A configured `campaign.cancelled` webhook is sent.

Archive a campaign to remove it from active lists without deleting its contacts, CDRs, or statistics. Cancel a running campaign before archiving it. Already archived campaigns return `409`.

<Warning>
  Treat cancel as irreversible. Verify the account and campaign ID before sending the request.
</Warning>

Invalid lifecycle transitions return `409 Conflict`.