# Add a transfer destination

Source: https://docs.usetone.ai/reference/transfer-destinations/create

> Creates a destination in `pending`.

`POST /v1/transfer-destinations`
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.

## Request body

| Field | Type | | Meaning |
|---|---|---|---|
| `e164` | string | required | 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. |
| `hours` | object[] | null | optional | 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 | required | 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. |
| `label` | string | required | What the person is called in the brief and the dashboard — "Delivery team". |
| `language` | string | optional | The language the person is briefed in. One of the eleven Tone's voices speak. |

### Example request

```json
{
  "e164": "+919876543210",
  "hours": [
    {
      "days": "mon-sat",
      "from": "09:30",
      "to": "19:00"
    }
  ],
  "key": "delivery_team",
  "label": "Delivery team",
  "language": "hi-IN"
}
```

## Response

| Field | Type | | Meaning |
|---|---|---|---|
| `createdAt` | string | required | RFC 3339, UTC. |
| `e164` | string | required | The number Tone rings. |
| `hours` | object[] | null | required | When it takes transfers, in IST. Null means at any time. |
| `id` | string | required | The destination's id. Agent configurations refer to it. |
| `key` | string | required | What agents and the call's model name it by. Fixed once created. |
| `label` | string | required | What the person is called in the brief and the dashboard. |
| `language` | string | required | The language the person is briefed in. |
| `status` | string | required | Where it stands. `pending` until the code from the verification call is confirmed; only `verified` can receive a transfer; `disabled` is switched off. Open set — handle an unrecognised value rather than throwing. Today: `pending`, `verified`, `disabled`. |
| `updatedAt` | string | required | RFC 3339, UTC. |
| `verification` | object | required | Where verification stands. |
| `verification.attemptsLeft` | integer | required | Wrong codes that may still be entered before a new call is needed. 0 when no code is waiting. |
| `verification.callsLeftToday` | integer | required | Verification calls this destination may still receive in the current 24 hours. |
| `verification.codeExpiresAt` | string | null | required | When the code from that call stops working. Null when no code is waiting. |
| `verification.lastCallAt` | string | null | required | When the last verification call was placed. |
| `verifiedAt` | string | null | required | When the code was confirmed. Null until then, and again after the number changes. |

### Example response

```json
{
  "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"
  }
}
```