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

# Campaigns API

> Operate campaign lifecycle end to end, including launch controls, analytics, exports, and rollback decisions.

# Campaigns are stateful orchestration objects, not static configs.

Use `bulk_call_campaigns` to manage dial strategy, schedule windows, and downstream reporting flows.

## Endpoint families

* Core CRUD: list/create/get/update
* Lifecycle controls: `launch`, `pause`, `resume`, `cancel`
* Cloning: `clone`, `clone_prefill`, `save_as_template`
* Runtime insight: `tasks`, `analytics`, `dispatch_health`
* Output paths: `results_export`, collection `export`
* Planning helpers: `capacity_preview`, `audience_timezone_analysis`

## Recommended lifecycle workflow

<Steps>
  <Step title="Create in draft state">
    Validate agent assignment, number pool, schedule timezone, and concurrency.
  </Step>

  <Step title="Run preflight checks">
    Use capacity and timezone analysis before first launch.
  </Step>

  <Step title="Launch and monitor dispatch health">
    Validate task creation, first outcomes, and number health.
  </Step>

  <Step title="Pause/resume for controlled tuning">
    Tune script, schedule, or concurrency using pause-resume loops.
  </Step>

  <Step title="Export and reconcile">
    Pull results export and analytics for CRM and BI handoff.
  </Step>
</Steps>

## Create and launch

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.callaro.ai/api/v1/bulk_call_campaigns" \
    -H "X-Api-Key: $CALLARO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name":"Q2 Pipeline Reactivation","agent_id":42,"timezone":"Asia/Kolkata","campaign_phone_number_ids":[101,102],"concurrency_limit":3}'

  curl -X POST "https://api.callaro.ai/api/v1/bulk_call_campaigns/123/launch" \
    -H "X-Api-Key: $CALLARO_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const create = await fetch('https://api.callaro.ai/api/v1/bulk_call_campaigns', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.CALLARO_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Q2 Pipeline Reactivation',
      agent_id: 42,
      timezone: 'Asia/Kolkata',
      campaign_phone_number_ids: [101, 102],
      concurrency_limit: 3
    })
  });
  const created = await create.json();
  await fetch(`https://api.callaro.ai/api/v1/bulk_call_campaigns/${created.data.id}/launch`, {
    method: 'POST',
    headers: { 'X-Api-Key': process.env.CALLARO_API_KEY }
  });
  ```
</CodeGroup>

## Monitor and control

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.callaro.ai/api/v1/bulk_call_campaigns?page=1&per_page=20" -H "X-Api-Key: $CALLARO_API_KEY"
  curl "https://api.callaro.ai/api/v1/bulk_call_campaigns/123/dispatch_health" -H "X-Api-Key: $CALLARO_API_KEY"
  curl "https://api.callaro.ai/api/v1/bulk_call_campaigns/123/analytics?from=2026-04-01&to=2026-04-30" -H "X-Api-Key: $CALLARO_API_KEY"
  curl -X POST "https://api.callaro.ai/api/v1/bulk_call_campaigns/123/pause" -H "X-Api-Key: $CALLARO_API_KEY"
  curl -X POST "https://api.callaro.ai/api/v1/bulk_call_campaigns/123/resume" -H "X-Api-Key: $CALLARO_API_KEY"
  ```

  ```javascript Node.js theme={null}
  await Promise.all([
    fetch('https://api.callaro.ai/api/v1/bulk_call_campaigns?page=1&per_page=20', { headers: { 'X-Api-Key': process.env.CALLARO_API_KEY } }),
    fetch('https://api.callaro.ai/api/v1/bulk_call_campaigns/123/dispatch_health', { headers: { 'X-Api-Key': process.env.CALLARO_API_KEY } }),
    fetch('https://api.callaro.ai/api/v1/bulk_call_campaigns/123/analytics?from=2026-04-01&to=2026-04-30', { headers: { 'X-Api-Key': process.env.CALLARO_API_KEY } }),
    fetch('https://api.callaro.ai/api/v1/bulk_call_campaigns/123/pause', { method: 'POST', headers: { 'X-Api-Key': process.env.CALLARO_API_KEY } })
  ]);
  ```
</CodeGroup>

## State transition guidance

| Current state  | Allowed action   | Operator intent                           |
| -------------- | ---------------- | ----------------------------------------- |
| Draft          | Launch           | Begin first execution window              |
| Running        | Pause            | Temporary stop for tuning/investigation   |
| Paused         | Resume or Cancel | Continue or terminate safely              |
| Running/Paused | Cancel           | End campaign and prevent further dispatch |

## Failure and rollback patterns

* If launch fails with validation errors, fix campaign configuration before retrying.
* If dispatch health degrades, pause campaign and investigate number health, schedule windows, or contact quality.
* If analytics mismatch appears, compare webhook dedupe logs with tasks and results export output.