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.

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.

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

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

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.

Get started

Voice

Account

Webhooks

Schedule a campaign

Create a campaign

Scheduling

List campaigns

Cancel future calls