> ## Documentation Index
> Fetch the complete documentation index at: https://docs.larynth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a number

> Buy a Larynth number, or keep your existing line and forward it.

Your agent answers calls on a phone number. You have two ways to get one.

| Option | Use it when |
| - | - |
| Buy a Larynth number | You want a new line for the agent. |
| Forward your existing number | You want callers to keep dialing the number they know. |

## Buy a number

**1. Search**

In the dashboard, open Numbers and search by area code or city. With the API, call `GET /v1/numbers/available`. Filter by `country`, `area_code`, `city`, `state` and `kind` (`local` or `toll_free`). `GET /v1/area-codes` finds US area codes from a city or code prefix.

**2. Order**

Order up to three numbers at once with `POST /v1/numbers/orders`, or one with `POST /v1/numbers`. The response of an order shows what is due now (the first month of every number) and the monthly total.

```bash theme={null}
curl https://api-us.larynth.com/v1/numbers/orders \
  -H "Authorization: Bearer $LARYNTH_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "local",
    "items": [{"e164": "+14155550100"}],
    "routing": {"open": {"mode": "assistant", "assistant_id": "'"$ASSISTANT_ID"'"}}
  }'
```

The first month is paid from your paid balance as each number is set up. Free credit does not cover number rental, so make a paid top-up first, or the order is refused with `numbers.paid_top_up_required`. See [Billing](https://docs.larynth.com/concepts/billing.md).

**3. Wait for it to be active**

Ordering is asynchronous. The number starts as `ordering` and becomes `active` when it is ready. Subscribe to the `number.provisioned` [webhook](https://docs.larynth.com/webhooks/events.md) if you want to be told.

**4. Choose who answers**

Route the number to a published agent, forward it to another phone, or leave it unanswered. See [Routing](#routing).

A number costs \$2 per month. Larynth numbers are US and Canadian. Calls on a number are billed as described in [Billing](https://docs.larynth.com/concepts/billing.md).

## Routing

Each number has a routing plan. The simple form is one choice in `route_type`: `assistant`, `forward` or `none`. Change it with `PATCH /v1/numbers/{id}`.

For more control, `PUT /v1/numbers/{id}/routing` replaces the whole plan:

* an open-hours target: an agent, or a forward to another US number;
* optional business hours with a time zone and holidays;
* an after-hours target: the same agent, a different agent, a forward, or take a message;
* a fallback number, `fallback_e164`, where a call goes to a person when the agent can't pick up. That covers a paused agent, an agent that fails to start, and the case where no engine answers. These transfers are not billed.

Send the number's `revision` back in the `If-Match` header, so you don't overwrite a change someone else made.

You can pause an agent with `POST /v1/assistants/{id}/pause`. Calls in progress finish, and new calls go to the forward line if you set one.

## Keep your existing number

Larynth does not port numbers yet. Buy a Larynth number and set your current provider to forward to it. Follow [Forward your number](https://docs.larynth.com/guides/forward-your-number.md).

Forwarded calls are shown on the number as `forward_sources`: the lines Larynth has seen forwarding to it.

## Release a number

`DELETE /v1/numbers/{id}` releases a number. It is asynchronous, and the status moves through `releasing` to `released`.

## Number status

`ordering`, `verifying`, `active`, `suspended`, `releasing`, `released` and `failed`.

> [!NOTE]
>
> A number that only forwards to another phone, with no agent on the call, is billed per minute at the forwarding rate on the rate card (`GET /v1/billing/rates`). Calls that go to your fallback line because the agent was paused or the service was unreachable are not billed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.