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 preserves the saved order outcome (201 confirmed number, 202 pending/unknown Australian order, or 200 definitively failed Australian order) without a second purchase. A different body returns 409 idempotency_conflict.

Maximum string length: 255

Body

application/json
phone_number
string
required

A US, Canada, India, or Australia 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
project_id
string

Required for Australian ordering; must be the owning active live project and match the authenticated project.

compliance_case_id
string

Required for Australian ordering. Select this project's approved new-number compliance application. Regulatory identifiers are resolved server-side; raw identifiers are never accepted.

max_monthly_cost_cents
integer

Required Australian order price ceiling in USD cents, taken from displayed inventory. An increased tariff above this ceiling is rejected before reserving or spending. Saved orders retain their original approved price.

Required range: x >= 1

Response

The saved Australian order was definitively rejected. This terminal receipt permits correcting the application and starting a new order.

object
enum<string>
required
Available options:
telephony.number_order
id
string
required
Example:

"tno_..."

status
enum<string>
required
Available options:
pending,
unknown,
completed,
failed,
released
phone_number
string
required
country
enum<string>
required
Available options:
AU
project_id
string
required
retry_after_seconds
integer
required
Required range: x >= 0
message
string
required
failure_code
string
number
object