Skip to main content
POST
/
v1
/
telephony
/
numbers
Provision (buy) a number
curl --request POST \
  --url https://api.pyai.com/v1/telephony/numbers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone_number": "+14155550123",
  "agent_id": "<string>"
}
'
{
  "object": "telephony.number",
  "id": "pn_...",
  "phone_number": "+14155550123",
  "country": "US",
  "area_code": "415",
  "capabilities": {
    "voice": true,
    "sms": true
  },
  "agent_id": "<string>",
  "recording": true,
  "monthly_cost_cents": 123,
  "created_at": 123,
  "released_at": 123
}

Authorizations

​
Authorization
string
header
required

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

Headers

​
Idempotency-Key
string

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

Maximum string length: 255

Body

application/json
​
phone_number
string
required

A US number (E.164) from the available-numbers search.

Example:

"+14155550123"

​
agent_id
string | null

Optional agent to route inbound calls to.

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

Carrier-side recording — always false; calls are recorded in PyAI's media bridge.

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

Unix ms.

​
released_at
integer | null

Unix ms.