Skip to main content
POST
Purchase 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

Inventory to buy from. Only the managed twilio inventory is purchasable (supports call transfer). The field discriminates so importing your own numbers can share this endpoint later.

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
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.