Phone Numbers

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 (or import one you already own), 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.

Request

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, `US` (default) or `CA`.
`area_code`	Restrict results to one area code, like `415`.
`number_type`	`local` (default). The managed inventory is US and Canada local numbers only; `toll_free` returns `400`.
`provider`	Inventory to search. Only `twilio` (the default) is available: managed numbers with call transfer support.

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.

Request

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.

Already have a number at your own carrier? The same endpoint imports it with provider: "sip" instead of buying one: no rental fee, no telephony charges. See Bring your own number.

List your numbers

Returns your team’s phone numbers across its workspaces, newest first; each carries its workspace_id.

Request

curl https://api.fish.audio/v1/agent/phone-numbers \
  --header "Authorization: Bearer $FISH_API_KEY"

Response

{
  "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

Request

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.

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" }'

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.

Request

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.

Request

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

Inbound calls

What happens when someone dials a bound number.

API introduction

API keys and workspace scoping for every request.

Conversation history

Review phone sessions, transcripts, and recordings.

Versions & publishing

Publish configuration changes behind a stable number.

Get Started

Build

Test

Deploy

Telephony

Monitor

Search available numbers

Purchase a number

List your numbers

Get a single number

Bind or unbind an agent

Label your numbers

Release a number

Going further

Inbound calls

API introduction

Conversation history

Versions & publishing

​Search available numbers

​Purchase a number

​List your numbers

​Get a single number

​Bind or unbind an agent

​Label your numbers

​Release a number

​Going further

Inbound calls

API introduction

Conversation history

Versions & publishing

Search available numbers

Purchase a number

List your numbers

Get a single number

Bind or unbind an agent

Label your numbers

Release a number

Going further