Tone docs
API referenceCampaigns

Apply the pre-flight exclusions and start dialling (requires Idempotency-Key)

🔴 Idempotency-Key is REQUIRED — without it this returns 400. Launching twice would dial the whole list twice, which is exactly the complaint pattern TCCCPR punishes. Refused if the agent is still a draft, if the number routes to your own stack, or if any pre-flight check blocks. Scrubbing runs here and MUST succeed: a scrubber outage fails the launch rather than passing an unscrubbed list.

Open in ClaudeOpen in ChatGPTView as Markdown

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

POST
/v1/campaigns/{id}/launch

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

Path Parameters

id*string

The campaign's id.

Header Parameters

Idempotency-Key*string

REQUIRED. A unique key of your choosing — a UUID is fine. Retrying with the same key replays the first response instead of acting twice, which is what makes a timeout safe to retry here. Reusing a key with a DIFFERENT body is 422 idempotency_key_reused_with_different_params; retrying while the first is still running is 409 idempotency_key_in_use. Keys are remembered for 24 hours.

Lengthlength <= 255

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/campaigns/string/launch" \  -H "Idempotency-Key: string"
{  "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?

Fetch a single campaign

Includes the snapshot taken at launch — the agent, the number and the sender classification the run actually used — which is evidence, not a live read of what those objects say today.

List campaigns, newest first (cursor-paginated)

Archived campaigns are hidden by default; pass archived=true to see only those. There is deliberately no way to ask for both at once.