Skip to main content
POST
Provision (buy) a number

Authorizations

Authorization
string
header
required

Use Authorization: Bearer pyai_live_... (or pyai_test_...).

Headers

Idempotency-Key
string
required

Required safe retry key. Reusing the key with an identical body replays the original 201 response (no second number purchase); reusing it with a different body returns 409 idempotency_conflict.

Maximum string length: 255

Body

application/json
phone_number
string
required

A US, Canada, or India number (E.164) from the available-numbers search.

Example:

"+14155550123"

agent_id
string | null

Optional agent to route inbound calls to.

provisioning_mode
enum<string>
default:automated

Use adopt_preowned only for a number already ordered through assisted provisioning. It never buys a number.

Available options:
automated,
adopt_preowned

Response

Provisioned

object
string
Example:

"telephony.number"

id
string
Example:

"pn_..."

phone_number
string

E.164.

Example:

"+14155550123"

country
string
Example:

"US"

area_code
string | null
Example:

"415"

capabilities
object
agent_id
string | null

Agent that answers inbound calls to this number.

recording
boolean

Whether PyAI recording is enabled for the number.

monthly_cost_cents
integer
status
enum<string>
Available options:
active,
released
created_at
integer

Unix ms.

released_at
integer | null

Unix ms.