Telephony

Provision (buy) a number

Buy a specific available number and attach it to your org, optionally binding it to an agent_id for inbound routing. When search reports assisted ordering, support may pre-order the number and you can explicitly set provisioning_mode=adopt_preowned; this never places a new order. Recording runs in PyAI's media bridge. Connected minutes bill on telephony.minutes ($0.01/min). Requires the telephony:manage scope.

post/v1/telephony/numbers

Request

  • Base URL: https://api.pyai.com
  • URL: https://api.pyai.com/v1/telephony/numbers
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Headers

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

Request body

phone_numberstring required

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

agent_idstring nullable

Optional agent to route inbound calls to.

provisioning_mode'automated' | 'adopt_preowned'

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

Example request

{
  "phone_number": "+14155550123"
}

Response

Provisioned

objectstring
idstring
phone_numberstring

E.164.

countrystring
area_codestring nullable
agent_idstring nullable

Agent that answers inbound calls to this number.

recordingboolean

Whether PyAI recording is enabled for the number.

monthly_cost_centsinteger
status'active' | 'released'
created_atinteger

Unix ms.

released_atinteger nullable

Unix ms.

Example response

{
  "object": "telephony.number",
  "id": "pn_...",
  "phone_number": "+14155550123",
  "country": "US",
  "area_code": "415"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.