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

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.

List your numbers

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

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

{
  "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 — nothing to redeploy.

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.

Authentication

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

Authentication

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

Authentication

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