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

# Schedule a campaign

A campaign schedules outbound calls to multiple recipients. Choose a configured agent and an eligible caller number from `GET /voice/phone-numbers`.

> [!WARNING]
>
> Campaign creation can schedule real, billable calls. Start with a single destination you control.

## Create a campaign

Save a unique `CAMPAIGN_REQUEST_ID` before submitting. Preserve it with the original body for retries.

```bash theme={null}
curl --fail-with-body 'https://api.getkarta.ai/public/v1/voice/campaigns' \
  -H "Authorization: Bearer $KARTA_API_KEY" \
  -H "X-Request-ID: $CAMPAIGN_REQUEST_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "campaign_name": "Example follow-up",
    "agent_id": "agentexample",
    "from_number": "+12025550124",
    "max_attempts": 1,
    "call_window": {
      "time_zone": "Asia/Kolkata",
      "days": [1, 2, 3, 4, 5, 6],
      "start": "10:00",
      "end": "18:00"
    },
    "call_details": [{
      "to_number": "+12025550123",
      "llm_dynamic_variable": {"customer_name": "Alex"},
      "transit_data": {"external_id": "example-001"}
    }]
  }'
```

Use `llm_dynamic_variable` to pass prompt variables for each recipient.

A `202` response includes `campaign_id` and `accepted_count`.

## Scheduling

* Use an IANA timezone such as `Asia/Kolkata`.
* Weekdays use Monday=1 through Sunday=7. Sunday is removed from mixed lists, so `[1, 7]` schedules Monday only. Empty and Sunday-only lists are rejected. Omit `days` or pass `null` to use Monday through Saturday.
* `start` must precede `end` within the daily calling window. Omitted or `null` times default to `10:00` and `21:00`.
* Omitted or `null` `start_date` defaults to the current UTC date, interpreted for scheduling in the chosen timezone. Send an explicit date when the distinction matters.
* `max_attempts` supports 1–4 and defaults to 1. For multiple attempts, set `time_gap_between_attempts` to at least 1 minute.
* Omit `end_date` and `max_concurrent_dials`, or pass `null`, to leave them unset.

## List campaigns

```bash theme={null}
curl --fail-with-body 'https://api.getkarta.ai/public/v1/voice/campaigns?limit=20' \
  -H "Authorization: Bearer $KARTA_API_KEY"
```

Follow `next_token` until it is null. Statuses include `active`, `running`, `inactive`, and `completed`.

## Cancel future calls

```bash theme={null}
curl --fail-with-body -X PATCH \
  "https://api.getkarta.ai/public/v1/voice/campaigns/$CAMPAIGN_ID" \
  -H "Authorization: Bearer $KARTA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"status":"inactive"}'
```

Cancellation stops future calls. It does not promise to terminate calls already in progress. Inactive and completed campaigns cannot be updated.


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