---
title: "Provision (buy) a number"
method: POST
path: "/v1/telephony/numbers"
tags: ["Telephony"]
---

# Provision (buy) a number

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

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.

## Headers

- `Idempotency-Key` string, required

## Request body

- TelephonyProvisionRequest
  - `phone_number` string, required: A US, Canada, or India number (E.164) from the available-numbers search.
  - `agent_id` string, 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.

## Response `201`

Provisioned

- TelephonyNumber
  - `object` string
  - `id` string
  - `phone_number` string: E.164.
  - `country` string
  - `area_code` string, nullable
  - `capabilities` object
    - `voice` boolean
    - `sms` boolean
  - `agent_id` string, nullable: Agent that answers inbound calls to this number.
  - `recording` boolean: Whether PyAI recording is enabled for the number.
  - `monthly_cost_cents` integer
  - `status` 'active' | 'released'
  - `created_at` integer: Unix ms.
  - `released_at` integer, nullable: Unix ms.

## Other responses

- `400`: Invalid request (bad field, unsupported value)
- `401`: Missing or invalid API key (`code: unauthorized`)
- `409`: That number is already provisioned (`code: number_in_use`), or the Idempotency-Key was reused with a different body (`code: idempotency_conflict`).

---

[API](https://skmtc.dev/pyai/apis/pyai-api.md) · [All operations](https://skmtc.dev/pyai/apis/pyai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pyai/apis/pyai-api/revisions/271a1539185b?raw)