Create a campaign (as a draft)

A campaign is a recipient list plus a pacing, retry and calling-window policy. It is created as a draft and dials nothing until you launch it. 🔴 agentId can never be changed afterwards — duplicate the campaign to use a different agent.

Requires the write scope. A key with less gets 403 insufficient_scope.

Authorization

AuthorizationBearer <token>

Authorization: Bearer tone_live_… or tone_test_…. The prefix IS the environment: a test key reaches only the sandbox, and no request field bridges the two.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

agentId*string

The agent every call in this campaign runs. Cannot be changed after creation — duplicate the campaign to use a different agent. Its purpose is snapshotted at launch and drives the compliance gate for the whole run.

Match

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Formatuuid

autoPauseBelowPaise?integer

Wallet floor in paise. When the balance falls below it the campaign pauses itself with pausedReason low_balance and emits campaign.paused, instead of dialling until calls start failing mid-conversation. Resume it after topping up.

Range0 <= value <= 9007199254740991

callsPerMinute?integer

How fast to dial, 1-60. The ceiling is the carrier's own campaign throttle, and bursts from a single caller ID are the pattern TCCCPR's spam rubric watches for — if you need more throughput, use more numbers rather than a higher rate.

Range1 <= value <= 60

endsAt?string

Stop dialling at this instant even if recipients remain. Must be later than startsAt.

maxConcurrent?integer

How many calls may be in flight at once, 1-20. 🔴 This does not queue above your organisation's concurrency quota — recipients dialled over it are refused and settle as failed. Check GET /v1/limits and keep this at or below what it reports.

Range1 <= value <= 20

name*string

Your label for the campaign. Shown in the dashboard and on every call it places.

Length1 <= length <= 120

numberId*string

The number to dial from. Must route to a Tone agent — a campaign on a BYO number is refused at launch rather than failing per call.

Match

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Formatuuid

retryAttempts?integer

How many times to redial a recipient whose outcome is in retryOn. 0-3; 0 disables retries.

Range0 <= value <= 3

retryBackoff?string

How the wait grows between successive retries. Open set — handle an unrecognised value rather than throwing. Today: linear, exponential.

Value in

"linear"
"exponential"

retryIntervalMinutes?integer

Minutes to wait before the first retry, 5-1440.

Range5 <= value <= 1440

retryOn?array<>

Which outcomes earn a retry. 🔴 answered is deliberately not accepted — redialling someone who already spoke to the agent is what turns a campaign into a complaint, and under TCCCPR five complaints in ten days bars every number your organisation owns.

Itemsitems <= 4

startsAt?string

Do not dial before this instant. Omit to start as soon as the campaign is launched.

weekdays?integer

Which weekdays may dial, as a 7-bit mask with Monday = bit 0 (0b0011111 = 31 = Mon-Fri, 127 = every day). 0 is refused: a campaign with no enabled weekday can never dial, and accepting it would leave it running and silently idle.

Range1 <= value <= 127

windowEndMinute?integer

Latest minute of the day this campaign may dial, as minutes past midnight IST (1260 = 21:00). 1440 is accepted so a window can run to midnight. Must be later than windowStartMinute, and the retry tail has to fit inside it too — a schedule whose retries would land outside the window is refused at launch.

Range0 <= value <= 1440

windowStartMinute?integer

Earliest minute of the day this campaign may dial, as minutes past midnight IST (540 = 09:00). Narrower than the legal band, never wider: the compliance gate still applies and will block a call this window would have allowed.

Range0 <= value <= 1439

Response Body

`application/json`

curl -X POST "https://example.com/v1/campaigns" \  -H "Content-Type: application/json" \  -d '{    "agentId": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",    "autoPauseBelowPaise": 50000,    "callsPerMinute": 10,    "endsAt": "2026-09-07T14:00:00Z",    "maxConcurrent": 4,    "name": "COD confirmations — September",    "numberId": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",    "retryAttempts": 1,    "retryBackoff": "fixed",    "retryIntervalMinutes": 60,    "retryOn": [      "no_answer",      "busy"    ],    "startsAt": "2026-09-01T04:00:00Z",    "weekdays": 31,    "windowEndMinute": 1260,    "windowStartMinute": 540  }'

{  "data": {    "agent": {      "id": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",      "name": "Order confirmation"    },    "archivedAt": null,    "autoPauseBelowPaise": 50000,    "completedAt": null,    "createdAt": "2026-08-25T09:14:22Z",    "environment": "live",    "id": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",    "launchedAt": "2026-09-01T04:00:00Z",    "name": "COD confirmations — September",    "number": {      "e164": "+918045678901",      "id": "4c8b1e77-3d2a-4f5b-9e6c-8a7b6c5d4e3f"    },    "pacing": {      "callsPerMinute": 10,      "maxConcurrent": 4    },    "pausedReason": "operator",    "preflight": {      "callable": 0,      "checks": [        {          "outcome": "pass",          "reason": "Outside the 09:00-21:00 IST window for promotional calls.",          "type": "time_window"        }      ],      "computedAt": "2026-09-01T03:58:12Z",      "estimatedCostPaise": {        "high": 480000,        "low": 120000      },      "excluded": "invalid_number",      "excludedE164s": {},      "total": 0,      "walletBalancePaise": 500000    },    "progress": {      "connected": 244,      "dialed": 320,      "excluded": 31,      "spentPaise": 146400,      "total": 500    },    "purpose": "transactional",    "retries": {      "attempts": 1,      "backoff": "linear",      "intervalMinutes": 60,      "on": [        "no_answer",        "busy"      ]    },    "schedule": {      "endsAt": "2026-09-07T14:00:00Z",      "startsAt": "2026-09-01T04:00:00Z",      "weekdays": 31,      "windowEndMinute": 1260,      "windowStartMinute": 540    },    "status": "running",    "updatedAt": "2026-08-25T09:14:22Z"  }}

Was this page helpful?

Create a campaign (as a draft)

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`