# Phone Numbers

Manage phone numbers for voice and text conversations. The Platform API handles the full lifecycle: telephony account provisioning, number search and purchase, workspace registration, call forwarding, and release.

## Typical Workflow

{% @mermaid/diagram content="%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#D4E2E7", "primaryTextColor": "#100F0F", "primaryBorderColor": "#083241", "lineColor": "#575452", "textColor": "#100F0F", "clusterBkg": "#F1EAE7", "clusterBorder": "#D7D2D0"}}}%%
flowchart TB
A\[Provision Account] --> B\[Search Numbers]
B --> C\[Purchase Number]
C --> D\[Update: Set Service]" %}

1. **Provision telephony account** - each workspace gets an isolated telephony account (idempotent)
2. **Search available numbers** - filter by area code, region, or capabilities
3. **Purchase a number** - automatically configures voice webhook routing to the Amigo platform
4. **Set inbound service** - update the phone number's `inbound_service_id` to route calls to a specific service

## Endpoints

| Method   | Path                                               | Description                                          |
| -------- | -------------------------------------------------- | ---------------------------------------------------- |
| `POST`   | `/v1/{workspace_id}/phone-numbers`                 | Register a phone number                              |
| `GET`    | `/v1/{workspace_id}/phone-numbers`                 | List phone numbers (paginated, filterable by status) |
| `GET`    | `/v1/{workspace_id}/phone-numbers/{id}`            | Get a phone number                                   |
| `PUT`    | `/v1/{workspace_id}/phone-numbers/{id}`            | Update a phone number                                |
| `DELETE` | `/v1/{workspace_id}/phone-numbers/{id}`            | Delete a phone number                                |
| `PUT`    | `/v1/{workspace_id}/phone-numbers/{id}/forwarding` | Set call forwarding                                  |
| `DELETE` | `/v1/{workspace_id}/phone-numbers/{id}/forwarding` | Clear call forwarding                                |

## Phone Number Fields

| Field                | Type           | Description                                       |
| -------------------- | -------------- | ------------------------------------------------- |
| `id`                 | string         | Unique identifier                                 |
| `phone_number`       | string         | E.164 format (e.g., `+18001234567`)               |
| `display_name`       | string         | Human-readable label (max 256 chars)              |
| `provider`           | string         | Telephony provider identifier                     |
| `capabilities`       | array          | `["inbound", "outbound"]`                         |
| `status`             | string         | `active` or `inactive`                            |
| `inbound_service_id` | string or null | Service that handles inbound calls to this number |
| `notes`              | string         | Free-text notes (max 2,000 chars)                 |
| `forwarding`         | object or null | Call forwarding configuration (see below)         |

## Call Forwarding

Forward calls to a fallback number when the agent should not handle them. Each phone number can have one forwarding configuration.

| Field               | Type    | Default  | Description                                                                                               |
| ------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `enabled`           | boolean | `true`   | Whether forwarding is active                                                                              |
| `forward_to`        | string  | required | Target phone number in E.164 format                                                                       |
| `should_disconnect` | boolean | `true`   | If true, the agent disconnects after transferring (warm transfer). If false, the agent stays on the line. |

Set forwarding with `PUT /phone-numbers/{id}/forwarding`. Clear it with `DELETE /phone-numbers/{id}/forwarding`.

## Filtering and Pagination

The list endpoint supports:

* `status` filter: `active` or `inactive`
* Cursor-based pagination with `limit` and `continuation_token`

## API Reference

* [Phone Numbers](https://docs.amigo.ai/api-reference/readme/platform/phone-numbers)