> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fish.audio/llms.txt
> Use this file to discover all available pages before exploring further.
# Phone Numbers
> Search, purchase, bind, and release phone numbers for your agents over the REST API
Phone numbers connect your agents to the telephone network. Each number lives in a workspace within your team (purchases land in your default workspace) and is bound to at most one agent — calls to the number are answered by that agent. The `/v1/agent/phone-numbers` API covers the whole lifecycle: search the purchasable inventory, buy a number, bind it to an agent, and release it when you no longer need it.
## Search available numbers
Search the purchasable inventory for a number to buy.
```bash Request theme={null}
curl "https://api.fish.audio/v1/agent/available-phone-numbers?country_code=US&area_code=415" \
--header "Authorization: Bearer $FISH_API_KEY"
```
The response is an `available_phone_numbers` array of inventory entries forwarded from the provider — number and region.
| Parameter | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `country_code` | ISO 3166-1 alpha-2 country code. Default `US`. |
| `area_code` | Restrict results to one area code, like `415`. |
| `number_type` | `local` (default). The managed inventory is US local numbers only; `toll_free` returns `400`. |
| `provider` | Inventory to search. Only `twilio` (the default) is available — managed numbers with [call transfer](/agents/telephony/transfers) support. |
Availability is not a reservation — a listed number can still be claimed by
someone else before you buy it.
## Purchase a number
Buy a number from the inventory with the same `provider` that listed it.
```bash Request theme={null}
curl --request POST https://api.fish.audio/v1/agent/phone-numbers \
--header "Authorization: Bearer $FISH_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"provider": "twilio",
"phone_number": "+14155550123",
"label": "Support line (US)",
"agent_id": "4f2a8c6e1b3d5f7a9c0e2d4b6a8f1c3e"
}'
```
Returns `201` with the number object — the same shape the list endpoint returns. The number lands in your default workspace, and its monthly price is billed in daily slices.
| Field | Description |
| -------------- | ------------------------------------------------------------------------ |
| `provider` | Required — `twilio`, the inventory the number came from. |
| `phone_number` | Required — an E.164 number from the search response. |
| `label` | Optional free-form label, up to 120 characters. |
| `agent_id` | Optional — bind an agent so the number answers inbound calls right away. |
A `409` means the number is already on the platform; a `502` means the provider refused the purchase — the number stays visible with status `error` and is safe to release.
## List your numbers
Returns your team's phone numbers across its workspaces, newest first — each carries its `workspace_id`.
```bash Request theme={null}
curl https://api.fish.audio/v1/agent/phone-numbers \
--header "Authorization: Bearer $FISH_API_KEY"
```
```json Response theme={null}
{
"phone_numbers": [
{
"phone_number_id": "7c9e6f2a4b8d4e1f9a3c5d7e8f0b1a2c",
"phone_number": "+14155550123",
"provider": "twilio",
"label": "Support line (US)",
"agent_id": "4f2a8c6e1b3d5f7a9c0e2d4b6a8f1c3e",
"status": "active"
}
],
"has_more": false
}
```
| Field | Description |
| ----------------- | ---------------------------------------------------------------- |
| `phone_number_id` | Unique identifier — use it in URL paths |
| `phone_number` | The number in E.164 format |
| `provider` | Telephony provider backing the number |
| `label` | Free-form label you assign |
| `agent_id` | The agent that answers calls to this number; `null` when unbound |
| `status` | `provisioning`, `active`, or `error` |
## Get a single number
```bash Request theme={null}
curl https://api.fish.audio/v1/agent/phone-numbers/$PHONE_NUMBER_ID \
--header "Authorization: Bearer $FISH_API_KEY"
```
Returns the same number object as the list endpoint.
## Bind or unbind an agent
`PATCH` the number with an `agent_id` to change which agent answers it. Binding is resolved per call, so the change applies from the next inbound call — nothing to redeploy.
```bash Bind theme={null}
curl --request PATCH https://api.fish.audio/v1/agent/phone-numbers/$PHONE_NUMBER_ID \
--header "Authorization: Bearer $FISH_API_KEY" \
--header "Content-Type: application/json" \
--data '{ "agent_id": "4f2a8c6e1b3d5f7a9c0e2d4b6a8f1c3e" }'
```
```bash Unbind theme={null}
curl --request PATCH https://api.fish.audio/v1/agent/phone-numbers/$PHONE_NUMBER_ID \
--header "Authorization: Bearer $FISH_API_KEY" \
--header "Content-Type: application/json" \
--data '{ "agent_id": null }'
```
Omitted fields are left unchanged — only an explicit `"agent_id": null` unbinds the number.
Re-binding is how you promote an agent behind a stable number: point the
number at a staging agent while you iterate, then `PATCH` it over to the
production agent when you're ready. The number itself never changes.
## Label your numbers
Labels are free-form text for keeping an inventory readable — by team, region, campaign, or environment.
```bash Request theme={null}
curl --request PATCH https://api.fish.audio/v1/agent/phone-numbers/$PHONE_NUMBER_ID \
--header "Authorization: Bearer $FISH_API_KEY" \
--header "Content-Type: application/json" \
--data '{ "label": "Support line (US)" }'
```
The response is the updated number object.
## Release a number
Release a number back to the provider's inventory. Returns `204`, daily billing stops, and the number disappears from the API immediately.
```bash Request theme={null}
curl --request DELETE https://api.fish.audio/v1/agent/phone-numbers/$PHONE_NUMBER_ID \
--header "Authorization: Bearer $FISH_API_KEY"
```
Releasing is irreversible. Anyone — including other platforms — can buy the
number afterwards, so callers who saved it may reach a stranger.
## Going further
What happens when someone dials a bound number.
API keys and workspace scoping for every request.
Review phone sessions, transcripts, and recordings.
Publish configuration changes behind a stable number.