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.
Requires the write scope. A key with less gets 403 insufficient_scope.
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
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.
length <= 255Request 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, "answeredAt": "2026-08-25T09:14:31Z", "billedPaise": 375, "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": 500, "startedAt": "2026-08-25T09:14:26Z", "status": "ended", "summary": "Customer confirmed the order and asked for Thursday delivery.", "transfer": { "acceptedAt": null, "answeredAt": "2026-10-13T10:01:41Z", "attempt": 1, "bridgedAt": "2026-10-13T10:01:52Z", "brief": "Transfer from Acme's digital assistant, about a complaint. This call is recorded. Press 1 to take the call.", "destination": { "label": "Delivery team" }, "endedAt": "2026-10-13T10:05:12Z", "hasRecording": true, "hasReturnRecording": false, "humanSeconds": 200, "id": "5b2c1e3d-9a4f-4e6b-8c7d-1f2e3a4b5c6d", "mode": "screened", "outcome": null, "reason": "out_of_scope", "requestedAt": "2026-10-13T10:01:30Z", "status": "bridged", "trigger": "model" }, "variables": { "customer_name": "Priya", "order_id": "AC-4417" }, "verdict": "success" }}Place the verification call
Tone calls the destination's number and speaks a six-digit code, valid for 15 minutes. Send it to POST /v1/transfer-destinations/{id}/confirm. Only a pending destination can be verified (409 conflict otherwise). Limits: one call a minute and three a day per destination, twenty a day per workspace (429 rate_limited). Needs a live key or the dashboard (422 environment_mismatch for a test key), because it rings a real phone.
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.