# Phone numbers

Source: https://docs.usetone.ai/phone-numbers

> Rent a real +91 line, decide who answers it, and keep it as long as you pay the rent.

A number is the only part of Tone that costs money whether or not you use it, and
the only part with a monthly anniversary. That shapes most of its behaviour.

## Getting one

In **test mode** a number is free and instant, and no carrier is contacted:

```bash
curl "$TONE_API/v1/numbers" -X POST \
  -H "Authorization: Bearer $TONE_KEY" -H 'content-type: application/json' \
  -d '{"series":"regular"}'
```

In **live mode** you search real carrier inventory and buy:

```bash
curl -H "Authorization: Bearer $TONE_KEY" \
  "$TONE_API/v1/numbers/available?number_type=landline&region=KA"

curl "$TONE_API/v1/numbers/purchase" -X POST \
  -H "Authorization: Bearer $TONE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'content-type: application/json' \
  -d '{"e164":"+918045678901","label":"Support line"}'
```

🔴 **`Idempotency-Key` is required here.** Without it you get a `400`. A duplicate
purchase buys a second number and starts a second monthly rental, and a timeout is
indistinguishable from a purchase that never happened — so retry with the *same*
key. See [Idempotency](/idempotency).

Buying needs completed business verification. `GET /v1/numbers/eligibility`
answers before you try.

Inventory is live, so results go stale: a number taken between your search and
your purchase is a `409 number_unavailable`. Search again and pick another.

## Who answers it

`routingMode` decides that, per number — one organization can mix all three.

| Mode | Who answers | Rate |
|---|---|---|
| `tone_agent` | A Tone agent you built | ₹6.00/min |
| `byo_ws` | Your own stack, over a WebSocket | ₹2.50/min |
| `byo_sip` | Your own SIP platform | see below |

```bash
curl "$TONE_API/v1/numbers/$NUMBER" -X PATCH \
  -H "Authorization: Bearer $TONE_KEY" -H 'content-type: application/json' \
  -d "{\"agentId\":\"$AGENT\"}"
```

Switching to a BYO mode **keeps** the bound agent — it is ignored while BYO and
restored when you switch back. Switching mode never reprices past calls: each
call snapshots its own mode at creation.

⚠️ A `byo_sip` number is **not dialable** through `POST /v1/calls`; the platform
reaches the carrier directly, so there is no pre-dial hook. Use
[the verdict API](/quickstart-compliance) as your pre-flight instead.

## Rent, and what happens when you stop paying

Purchase debits setup plus the first month and sets an anniversary. On each
anniversary the rental is debited. Anniversaries clamp at month end, so a number
bought on 31 January renews on 28 February and stays on the 28th thereafter.

If the wallet cannot cover it:

1. A **grace period** starts, with an email to owners and admins on day one.
2. Past grace the number is **suspended** — it refuses calls in both directions
   and emits `number.suspended`.
3. Top up, and it **reactivates on its own**, emitting `number.reactivated`.

🔴 **A suspended number keeps your claim on the line.** Unpaid rent is not a
release: freeing the number would sell your published phone number to a stranger.

## Releasing

```bash
curl "$TONE_API/v1/numbers/$NUMBER" -X DELETE -H "Authorization: Bearer $TONE_KEY"
```

🔴 Permanent. The number returns to general carrier inventory and anyone can buy
it. If you only want to stop paying, note that not paying suspends rather than
releases, and reverses itself.

## The 140 and 160 series

`140` (telemarketing) and `160` (transactional, BFSI) exist in the regulations
and in `NUMBER_SERIES`, and both require an approved DLT Principal Entity ID.
**Neither is purchasable through a carrier API today** — search and purchase only
ever offer regular numbers. We would rather say so than show you a Buy button
that cannot work.