Tonedocs
API referencetransfer-destinations

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.

Open in ClaudeOpen in ChatGPTView as Markdown

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

POST
/v1/transfer-destinations/{id}/verify

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 transfer destination's id.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/transfer-destinations/string/verify"
{  "data": {    "createdAt": "2026-10-13T09:20:00.000Z",    "e164": "+919876543210",    "hours": [      {        "days": "mon-sat",        "from": "09:30",        "to": "19:00"      }    ],    "id": "7d1f5c9e-2b3a-4c8d-9e0f-1a2b3c4d5e6f",    "key": "delivery_team",    "label": "Delivery team",    "language": "hi-IN",    "status": "verified",    "updatedAt": "2026-10-13T09:30:00.000Z",    "verification": {      "attemptsLeft": 5,      "callsLeftToday": 2,      "codeExpiresAt": "2026-10-13T09:43:10.000Z",      "lastCallAt": "2026-10-13T09:28:10.000Z"    },    "verifiedAt": "2026-10-13T09:30:00.000Z"  }}
Was this page helpful?

Update a transfer destination

Change the label, language, hours or number. The key is fixed. 🔴 A new number puts the destination back to pending: the person at the new number has not consented yet, so it must be verified again.

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.