Add a transfer destination

Creates a destination in pending. It cannot receive a transfer until it is verified: place a verification call with POST /v1/transfer-destinations/{id}/verify, then send the code it speaks to POST /v1/transfer-destinations/{id}/confirm. 409 conflict when the key is already taken.

Requires the admin 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.

e164*string

The number to ring: a +91 mobile, or a landline with its STD code, in E.164. Toll-free, premium-rate and other special numbers are refused.

Match^\+91[2-9]\d{9}$

hours?array<>|

When it takes transfers, in IST. Null or an empty list means at any time. Outside these windows the agent tells the caller nobody is available instead of dialling.

key*string

What agents name this destination by — delivery_team. Unique in your workspace and fixed once created, because published agent versions and the call's model refer to it.

Match^[a-z][a-z0-9_]{1,39}$

label*string

What the person is called in the brief and the dashboard — "Delivery team".

Match^[^\p{C}]+$

Length1 <= length <= 60

language?string

The language the person is briefed in. One of the eleven Tone's voices speak.

Default"hi-IN"

Value in

"hi-IN"
"en-IN"
"bn-IN"
"gu-IN"
"kn-IN"
"ml-IN"
"mr-IN"
"od-IN"
"pa-IN"
"ta-IN"
"te-IN"

Response Body

`application/json`

curl -X POST "https://example.com/v1/transfer-destinations" \  -H "Content-Type: application/json" \  -d '{    "e164": "+919876543210",    "hours": [      {        "days": "mon-sat",        "from": "09:30",        "to": "19:00"      }    ],    "key": "delivery_team",    "label": "Delivery team",    "language": "hi-IN"  }'

{  "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?

Add a transfer destination

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`