Skip to main content
POST
Purchase or Import Phone Number

Authorizations

Authorization
string
header
required

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

Body

application/json
provider
string
required

twilio buys from the managed inventory (supports call transfer); sip imports a number you already own at your carrier; see the sip request variant.

Allowed value: "twilio"
phone_number
string
required

E.164 number from GET /v1/agent/available-phone-numbers, e.g. +14155550123.

label
string
default:""
Maximum string length: 120
agent_id
string | null

Bind an agent to answer inbound calls right away.

Response

Document created, URL 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:""
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.