Sign in
Phone Numbers

Provision Phone Number

post/api/v1/phone/numbers

Request body

agent_handlestring required

Agent identity handle to assign this number to (e.g. 'sales-agent' or '@sales-agent').

type'local' | 'toll_free'
statestring nullable

US state abbreviation (e.g. 'NY', 'CA'). Only used for local numbers.

incoming_call_action'auto_accept' | 'auto_reject' | 'webhook' | 'hosted_agent' | 'forward'
client_websocket_urlstring nullable

WebSocket URL (wss://) for audio bridging. Required when incoming_call_action is 'auto_accept'.

incoming_call_webhook_urlstring nullable

Webhook URL for incoming call notifications. Required when incoming_call_action is 'webhook'.

forwarding_target_type'phone' | 'sip'
forwarding_phone_numberstring nullable

Phone number in E.164 format (e.g. '+15551234567').

forwarding_sip_uristring nullable

Complete SIP destination in sip:user@host format.

Example request

{
  "forwarding_phone_number": "+15551234567",
  "forwarding_sip_uri": "sip:line@voice.example.com"
}

Response

Successful Response

idstring uuid required
numberstring required
type'local' | 'toll_free' required
status'active' | 'paused' | 'released' required
sms_status'pending' | 'ready' | 'assignment_failed' required
sms_error_codestring nullable
sms_error_detailstring nullable
sms_ready_atstring date-time nullable
incoming_call_action'auto_accept' | 'auto_reject' | 'webhook' | 'hosted_agent' | 'forward' required
client_websocket_urlstring nullable required
incoming_call_webhook_urlstring nullable required
forwarding_target_type'phone' | 'sip'
forwarding_phone_numberstring nullable
forwarding_sip_uristring nullable
filter_mode'whitelist' | 'blacklist' required
statestring nullable

2-letter US state abbreviation for LOCAL numbers (e.g. 'NY'). Null for toll-free numbers.

agent_identity_idstring uuid nullable

ID of the agent identity that owns this phone number, or null if the number is standalone (not tied to any agent).

created_atstring date-time required
updated_atstring date-time required

Changes

No recorded changes to this endpoint across all 1 revision of this API.