Phone Numbers — client.phone_number

Register numbers and manage their SIP connections.

create(**params) → PhoneNumberResponse

POST /v1/phone-numbers

Param	Type	Required	Default	Description
phone_number	str	yes	—	E.164 number.
nickname	str	no	None	Friendly name.
provider	str	no	"custom"	custom, netgsm, twilio, telnyx.
inbound_agent_id	str	no	None	Agent for inbound calls.
outbound_agent_id	str	no	None	Agent for outbound calls.
allowed_inbound_countries	list[str]	no	["*"]	Inbound country whitelist.
allowed_outbound_countries	list[str]	no	["*"]	Outbound country whitelist.
inbound_webhook_url	str	no	None	Webhook for inbound events.

Returns PhoneNumberResponse: phone_number_id, phone_number, nickname, provider, inbound_agent_id, outbound_agent_id, status, created_at.

retrieve(phone_number_id) → PhoneNumberDetailResponse

GET /v1/phone-numbers/{id} — includes sip_connections and dispatch_rules.

list(skip=0, limit=50) → list[PhoneNumberResponse]

GET /v1/phone-numbers

update(phone_number_id, **params) → PhoneNumberResponse

PATCH /v1/phone-numbers/{id} — update nickname, provider, inbound_agent_id, outbound_agent_id, country whitelists, or inbound_webhook_url.

⚠️ update_agents() is NOT usable in the current release — calling it raises AttributeError. To assign agents to a number, use update(...) instead (this works today): client.phone_number.update(pid, inbound_agent_id="ag_xyz", outbound_agent_id="ag_abc"). See Known issues.

delete(phone_number_id) → None

DELETE /v1/phone-numbers/{id} — deletes the number and its SIP connections.

SIP connections (nested under a phone number)

A SIP connection carries the carrier trunk details (termination URI + credentials) and auto-syncs to the telephony layer.

• create_sip_connection(phone_number_id, termination_uri, username=None, password=None, nickname=None, connection_type="inbound", transport="TCP") → SIPConnectionResponse — connection_type ∈ inbound|outbound|both, transport ∈ TCP|UDP|TLS.
• list_sip_connections(phone_number_id) → list[SIPConnectionResponse]
• retrieve_sip_connection(phone_number_id, connection_id) → SIPConnectionResponse
• update_sip_connection(phone_number_id, connection_id, **params) → SIPConnectionResponse
• delete_sip_connection(phone_number_id, connection_id) → None
• sync_sip_connection(phone_number_id, connection_id) → SIPConnectionResponse — force re-sync.

SIPConnectionResponse: sip_connection_id, phone_number_id, termination_uri, username, nickname, connection_type, transport, livekit_trunk_id, sync_status, sync_error, created_at, updated_at.

---