> ## 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.

# Telephony API

> Phone numbers, trunks, inbound routing, and number purchasing over HTTP.

Telephony endpoints live under the `/core` prefix and cover the phone-number directory, SIP trunks, the org-level inbound-routing config, and number purchasing through a managed account. Pass your credential in the `Authorization` header; user PATs (`pat_`) also need `X-Anyreach-Org`. See [Authentication](/api-reference/authentication).

Assigning an agent to a number is done through the agent **publish** endpoint, not here — see [Agents API](/api-reference/agents/overview) and [Assigning agents to numbers](/telephony/assigning-agents-to-numbers).

## Phone numbers

| Method   | Path                                 | Scope                  | Description                                                                                                                    |
| -------- | ------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `GET`    | `/core/phone-numbers`                | `phone_numbers:read`   | List numbers. Filters: `phone_number` (substring), `trunk_id`, `created_*`/`updated_*`. Cursor pagination (`limit`, `cursor`). |
| `GET`    | `/core/phone-numbers/{phone_number}` | `phone_numbers:read`   | Get one number.                                                                                                                |
| `POST`   | `/core/phone-numbers`                | `phone_numbers:manage` | Register a number on a non-managed trunk (`trunk_id` required). Subject to the per-org number limit.                           |
| `PATCH`  | `/core/phone-numbers/{phone_number}` | `phone_numbers:manage` | Toggle `outbound_shareable` only — no other field is editable.                                                                 |
| `DELETE` | `/core/phone-numbers/{phone_number}` | `phone_numbers:manage` | Remove a number.                                                                                                               |

## Buying a number

Self-serve purchase goes through a managed account (the shared Anyreach Twilio account).

| Method | Path                                                          | Scope                     | Description                                                                                                                                                                                             |
| ------ | ------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET`  | `/core/managed-accounts/{managed_account_id}/search-numbers`  | `managed_accounts:read`   | Search available numbers. Filters: `area_code`, `country_code` (default `US`), `phone_number_type` (`local`/`toll_free`), `voice_enabled`, `sms_enabled`, `mms_enabled`, `in_region`, `in_postal_code`. |
| `POST` | `/core/managed-accounts/{managed_account_id}/purchase-number` | `managed_accounts:manage` | Buy a number (`phone_number`) and create its directory row.                                                                                                                                             |

## SIP trunks

Trunk CRUD models SIP connectivity. Customer-owned (BYOC) trunks are fully editable; managed Twilio trunks cannot be created, updated, or deleted through the API.

| Method   | Path                | Scope           | Description                                                                   |
| -------- | ------------------- | --------------- | ----------------------------------------------------------------------------- |
| `GET`    | `/core/trunks`      | `trunks:read`   | List trunks.                                                                  |
| `GET`    | `/core/trunks/{id}` | `trunks:read`   | Get one trunk.                                                                |
| `POST`   | `/core/trunks`      | `trunks:manage` | Create a customer-owned trunk with `inbound_config` and/or `outbound_config`. |
| `PUT`    | `/core/trunks/{id}` | `trunks:manage` | Update a customer-owned trunk.                                                |
| `DELETE` | `/core/trunks/{id}` | `trunks:manage` | Delete a customer-owned trunk.                                                |

See [SIP trunking and BYOC](/telephony/sip-and-byoc) for the inbound/outbound config fields and the `deploy-as-sip` endpoints (under [Agents API](/api-reference/agents/overview)).

## Inbound routing

One config per organization runs a workflow at call time to choose the agent.

| Method   | Path                           | Scope                            | Description                                             |
| -------- | ------------------------------ | -------------------------------- | ------------------------------------------------------- |
| `GET`    | `/core/inbound-routing-config` | `inbound_routing_configs:read`   | Get the org's config, or `null` if none exists.         |
| `POST`   | `/core/inbound-routing-config` | `inbound_routing_configs:manage` | Create the config. Returns `409` if one already exists. |
| `PUT`    | `/core/inbound-routing-config` | `inbound_routing_configs:manage` | Update the config.                                      |
| `DELETE` | `/core/inbound-routing-config` | `inbound_routing_configs:manage` | Remove the config.                                      |

The workflow's input and output contracts are documented in [Inbound routing](/telephony/inbound-routing).

## Example: list phone numbers

```bash theme={null}
curl "https://api.anyreach.ai/core/phone-numbers?limit=50" \
  -H "Authorization: Bearer $ANYREACH_TOKEN" \
  -H "X-Anyreach-Org: $ANYREACH_ORG_ID"
```

## Related

<CardGroup cols={2}>
  <Card title="Telephony" icon="phone" href="/telephony/overview">
    The product walkthrough for numbers, routing, and BYOC.
  </Card>

  <Card title="Agents API" icon="robot" href="/api-reference/agents/overview">
    Publish and assign agent versions to numbers.
  </Card>
</CardGroup>