FIfish
Phone Numbers

Purchase or Import Phone Number

Changed on

provider discriminates two variants. twilio buys a number from the managed inventory: it lands in your default workspace, any agent_id you bind must live there too, and billing is the monthly price charged in daily slices; the first day is charged before anything is bought (402 costs you nothing) and the daily run advances it from there. sip imports a number you already own at your carrier: point your trunk's origination at our SIP host, provide inbound authentication (digest and/or source CIDRs) and optionally a termination host so the number can place calls; nothing is rented and there is no monthly fee. Either way, 409 means the number is already on the platform; 502 means the provider or trunk provisioning refused, and the number stays visible with status error and is safe to release.

post/v1/agent/phone-numbers

Request

  • Base URL
    https://api.fish.audio
  • URL
    https://api.fish.audio/v1/agent/phone-numbers
  • Auth
    HTTP bearer

Request body

OR

Response

Document created, URL follows

phone_number_idstring required
workspace_idstring required
phone_numberstring required

E.164, e.g. +14155550123.

provider'livekit' | 'twilio' | 'sip' | 'whatsapp' required
labelstring
agent_idstring nullable required

Inbound calls route to this agent; unbound numbers ring busy.

transfer_caller_id'agent_number' | 'original_caller' nullable

Managed twilio numbers: the caller ID a transfer target sees, on cold and warm transfers alike. agent_number shows this number, original_caller shows the caller's own number (a warm transfer falls back to this number when the caller withholds theirs). null for imported sip numbers, whose carrier decides.

cold_transfer_use_original_callerboolean nullable

Deprecated, read transfer_caller_id. True when it is original_caller.

cold_transfer_use_original_caller_effectiveboolean nullable

Deprecated, read caller_id_sync_status. Whether the carrier has confirmed the original caller policy for cold transfers, null while unknown.

caller_id_sync_status'synced' | 'pending' | 'error' | 'carrier_managed'

synced once the carrier confirmed the policy, pending while it is being applied, error when the last attempt failed (send retry_caller_id_sync), carrier_managed for imported sip numbers.

caller_id_sync_errorstring

Why the last synchronization failed; empty otherwise.

status'provisioning' | 'active' | 'error' | 'released' required
status_detailstring

What failed when status is error; empty otherwise.

supports_outboundboolean

Whether the number can place calls (outbound and warm-transfer consult legs): managed twilio always, imported sip only when a termination was configured.

termination_uristring nullable

Imported sip numbers: the customer trunk's termination host.

inbound_auth_usernamestring nullable

Imported sip numbers: the inbound digest username. Passwords are never echoed.

inbound_allowed_addressesstring[]

Imported sip numbers: allowed source IPs/CIDRs.

termination_transportstring nullable

Imported sip numbers: termination transport.

termination_auth_usernamestring nullable

Imported sip numbers: the termination digest username. Passwords are never echoed.

termination_headersobject

Imported sip numbers: custom SIP headers added to every outbound INVITE through the termination.

created_atstring date-time required
updated_atstring date-time required

Changes