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

# Buying a number

> Search and purchase a phone number for your agents.

A phone number is what connects your agents to the public telephone network. Buy one directly from the dashboard: search by area code, then purchase with a single click. Anyreach provisions the number on a shared managed account and binds it to a trunk for you, so there is no carrier setup to do.

## Search and purchase

Open the **Phone Numbers** page and start a purchase. The first time the dialog opens it runs a search automatically; type an area code and click **Search** to narrow the results.

<Steps>
  <Step title="Open the purchase dialog">
    Click **Purchase**. If you have no numbers yet, the empty state has a button that opens the same dialog.
  </Step>

  <Step title="Search by area code">
    Enter an area code in **Search by area code** and click **Search**. Leave it blank to see whatever is currently available.
  </Step>

  <Step title="Purchase a number">
    Click **Purchase** next to the number you want. Anyreach buys it, creates a trunk, and adds it to your directory.
  </Step>
</Steps>

The dashboard always searches for **US**, **local**, **voice-enabled** numbers on the shared Anyreach managed account. You never choose or see the managed account; that detail is handled for you.

<Note>
  You need the `phone_numbers:manage` or `managed_accounts:manage` scope to purchase a number. Reading the directory requires `phone_numbers:read` or `phone_numbers:manage`.
</Note>

## Number directory

The **Phone Numbers** page lists every number on your organization.

| Column         | Description                                                                         |
| -------------- | ----------------------------------------------------------------------------------- |
| Phone Number   | The purchased number in E.164 form.                                                 |
| Inbound Agent  | Agent (and version) that answers calls to this number, or `-` if none.              |
| Outbound Agent | Agent (and version) that places calls from this number, or `-` if none.             |
| Shareable      | Toggle that controls whether the number can be used for outbound by shared callers. |
| Created At     | When the number was purchased.                                                      |
| Updated At     | When the number's assignment last changed.                                          |

Click a row to open its assignment dialog. To assign or change agents, see [Assigning agents to numbers](/telephony/assigning-agents-to-numbers).

The **Shareable** switch is the only field you can edit inline. It maps to `outbound_shareable` and is updated through `PATCH /core/phone-numbers/{phone_number}`, which intentionally accepts only that field. Trunk rebinding is not exposed.

## API reference

The dashboard fixes most filters, but the API exposes the full search.

### Search available numbers

```
GET /core/managed-accounts/{managed_account_id}/search-numbers
```

| Parameter           | Type    | Default | Description                       |
| ------------------- | ------- | ------- | --------------------------------- |
| `area_code`         | integer | —       | Restrict results to an area code. |
| `phone_number_type` | enum    | `local` | `local` or `toll_free`.           |
| `country_code`      | string  | `US`    | Country to search in.             |
| `voice_enabled`     | boolean | —       | Require voice capability.         |
| `sms_enabled`       | boolean | —       | Require SMS capability.           |
| `mms_enabled`       | boolean | —       | Require MMS capability.           |
| `in_postal_code`    | string  | —       | Restrict to a postal code.        |
| `in_region`         | string  | —       | Restrict to a region.             |

```bash theme={null}
curl "https://api.anyreach.ai/core/managed-accounts/{managed_account_id}/search-numbers?area_code=415&country_code=US&phone_number_type=local&voice_enabled=true" \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>"
```

### Purchase a number

```
POST /core/managed-accounts/{managed_account_id}/purchase-number
```

```bash theme={null}
curl -X POST "https://api.anyreach.ai/core/managed-accounts/{managed_account_id}/purchase-number" \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155550123" }'
```

The response includes the number, its `trunk_id`, and `managed_account_id`.

<Info>
  User PATs (`pat_`) require the `X-Anyreach-Org` header shown above. Org API keys (`ak_`) carry their organization implicitly, so omit the header. Search accepts `managed_accounts:read` or `managed_accounts:manage`; purchase requires `managed_accounts:manage`.
</Info>

## Limits

| Limit                          | Behavior                                                                                                                                  |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Phone numbers per organization | Enforced by your plan. Purchasing past the limit fails with "You have reached the maximum number of phone numbers for your organization." |

See [Plans and billing](/organizations/plans-and-billing) to review or raise your limit.

## Bringing your own number

There is no self-serve UI to import an existing or customer-owned number. To route calls through your own carrier or an existing DID, set up a BYOC trunk through the API or contact support.

<CardGroup cols={2}>
  <Card title="SIP and BYOC" icon="network-wired" href="/telephony/sip-and-byoc">
    Connect your own carrier or SIP trunk instead of buying a number.
  </Card>

  <Card title="Assigning agents to numbers" icon="user-plus" href="/telephony/assigning-agents-to-numbers">
    Point inbound and outbound calls at the right agent.
  </Card>
</CardGroup>