Tone docs
API referenceCalls

Place an outbound call (runs the compliance gate)

Runs the full pre-dial compliance gate inside the same transaction, so a refusal is a 403 with the audit rows already written and no carrier contacted. Requires agentId on a number that routes to a Tone agent and forbids it on a BYO number. Over your concurrent-call quota this returns 429 BEFORE the gate runs, so no verdict is recorded. Send an Idempotency-Key — a timeout is otherwise indistinguishable from a call you did not place.

Open in ClaudeOpen in ChatGPTView as Markdown

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

POST
/v1/calls

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

Header Parameters

Idempotency-Key?string

Optional but recommended. Retrying with the same key replays the first response instead of placing a second call. Reusing a key with a different body is 422; a concurrent duplicate is 409. Keys are remembered for 24 hours.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/calls" \  -H "Content-Type: application/json" \  -d '{    "agentId": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",    "numberId": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",    "toE164": "+919876543210"  }'
{  "data": {    "agent": {      "id": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",      "name": "Order confirmation"    },    "agentVersion": 3,    "billedPaise": 600,    "campaignId": null,    "channel": "pstn",    "compliance": "passed",    "createdAt": "2026-08-25T09:14:22Z",    "direction": "outbound",    "disposition": "answered",    "durationSeconds": 45,    "endReason": "agent_ended",    "endedAt": "2026-08-25T09:15:11Z",    "environment": "live",    "evaluations": {},    "hasRecording": true,    "hasTranscript": true,    "id": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",    "initiator": {      "id": "key_8f14a2c9",      "type": "api_key"    },    "number": {      "e164": "+918045678901",      "id": "4b7c1a02-9de5-4f31-bb07-2c1a5e9f0d43"    },    "outputs": {      "confirmed": true,      "delivery_day": "Thursday"    },    "peer": "+919876543210",    "quality": {      "answerP50Ms": 480,      "perceivedP50Ms": 0,      "turns": 6    },    "ratePaisePerMinute": 600,    "startedAt": "2026-08-25T09:14:26Z",    "status": "ended",    "summary": "Customer confirmed the order and asked for Thursday delivery.",    "variables": {      "customer_name": "Priya",      "order_id": "AC-4417"    },    "verdict": "success"  }}
Was this page helpful?

Rename a number or bind it to an agent

Also where you switch who answers it. Send null to clear a field; omit the key to leave it alone. Switching to a BYO routing mode KEEPS the bound agent — it is ignored while BYO and restored when you switch back.

Fetch a call's sealed evidence record

The tamper-evident evidence document for this call: the legal basis it was placed on (DNC, consent, carrier signal), how it was placed (DLT registration, A2P declaration, calling window, AI disclosure), the outcome, and the hash-chain seal. Available shortly after the call ends.