Skip to main content
PATCH
Update Phone Number

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

phone_number_id
string
required

Body

application/json
label
string | null
Maximum string length: 120
agent_id
string | null

Agent that answers this number's inbound calls. Explicit null unbinds; omit the field to keep the current binding.

transfer_caller_id
enum<string> | null

Managed twilio numbers only: the caller ID a transfer target sees, agent_number (this number) or original_caller (the caller's own number). Applies to cold and warm transfers. It is a number setting, not agent config: no publish is needed and agent rollbacks leave it alone. Warm transfers follow it from the next call, cold transfers once caller_id_sync_status is synced. The deprecated boolean cold_transfer_use_original_caller is still accepted in its place.

Available options:
agent_number,
original_caller
retry_caller_id_sync
boolean
default:false

Re-apply the current caller ID policy after a failed synchronization.

Response

Request fulfilled, document follows

phone_number_id
string
required
workspace_id
string
required
phone_number
string
required

E.164, e.g. +14155550123.

provider
enum<string>
required
Available options:
livekit,
twilio,
sip
agent_id
string | null
required

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

status
enum<string>
required
Available options:
provisioning,
active,
error,
released
created_at
string<date-time>
required
updated_at
string<date-time>
required
label
string
default:""
transfer_caller_id
enum<string> | null

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.

Available options:
agent_number,
original_caller
cold_transfer_use_original_caller
boolean | null
deprecated

Deprecated, read transfer_caller_id. True when it is original_caller.

cold_transfer_use_original_caller_effective
boolean | null
deprecated

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
enum<string>
default: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.

Available options:
synced,
pending,
error,
carrier_managed
caller_id_sync_error
string
default:""

Why the last synchronization failed; empty otherwise.

status_detail
string
default:""

What failed when status is error; empty otherwise.

supports_outbound
boolean
default:false

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

termination_uri
string | null

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

inbound_auth_username
string | null

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

inbound_allowed_addresses
string[]

Imported sip numbers: allowed source IPs/CIDRs.

termination_transport
string | null

Imported sip numbers: termination transport.

termination_auth_username
string | null

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

termination_headers
Termination Headers · object

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