Docs · Build · Phone numbers

Phone numbers.

A published agent already takes calls in the browser. To reach it over the phone network, give it a number: buy one on the platform, import a number you already own, or bring your own SIP trunk. Telephony is billed at cost and never marked up — and a BYO SIP trunk carries $0 telephony, because the minutes run on your carrier.

Provision a number#

POST/v1/phone-numbers

One endpoint covers every way a number can arrive. The action decides whether the platform allocates a number, adopts one you own, or wires up your SIP trunk. Every number answers as exactly one agent.

Field	Type		Description
agent_id	string	required	The agent that answers calls to this number and places outbound calls from it.
action	string	required	One of `buy` (allocate a platform number), `import` (a number you already own), `byo` (route through your own SIP trunk), or `release`.
country	string	buy	ISO-2 country code for the number to allocate — e.g. `SA`, `AE`, `EG`. Required when `action` is `buy`.
e164	string	import · byo · release	The number in E.164 form, e.g. `+966920000123`. Identifies the number to import, attach to your trunk, or release.
provider	string	byo	For `byo`, how your trunk connects — `"twilio"`, `"telnyx"`, or `"sip"` for a generic SIP carrier. Platform numbers report `provider: "platform"`.
credentials	object	byo sip	Connection details for a generic SIP trunk — SIP URI, username, password, and transport. Held encrypted at rest and used only to route calls to your carrier.

Request · buy a platform number

curl -X POST https://voice.whizztech.ai/v1/phone-numbers \
  -H "Authorization: Bearer $WHIZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "ag_7Q2c51b84a07",
    "action": "buy",
    "country": "SA"
  }'

Response · 201 Created

{
  "id": "pn_5b8f0d21",
  "object": "phone_number",
  "e164": "+966920000123",
  "country": "SA",
  "agent_id": "ag_7Q2c51b84a07",
  "provider": "platform",
  "status": "active",
  "inbound": true,
  "outbound": true,
  "monthly_usd": 2.0,
  "per_min_usd": 0.015,
  "created_at": "2026-07-13T09:34:11.000Z"
}

Bringing your own trunk looks the same, minus the platform's per-minute telephony rate — the minutes bill on your carrier, so per_min_usd comes back 0. You still pay your voice rate per second for the agent itself.

Request · bring your own SIP trunk

curl -X POST https://voice.whizztech.ai/v1/phone-numbers \
  -H "Authorization: Bearer $WHIZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "ag_7Q2c51b84a07",
    "action": "byo",
    "e164": "+966920000456",
    "provider": "sip",
    "credentials": {
      "sip_uri": "sip:whizz@trunk.example.net:5060",
      "username": "whizz-egress",
      "password": "$SIP_TRUNK_SECRET",
      "transport": "tls"
    }
  }'

Response · 201 Created

{
  "id": "pn_a1c93e70",
  "object": "phone_number",
  "e164": "+966920000456",
  "country": "SA",
  "agent_id": "ag_7Q2c51b84a07",
  "provider": "sip",
  "status": "active",
  "inbound": true,
  "outbound": true,
  "monthly_usd": 0,
  "per_min_usd": 0,
  "created_at": "2026-07-13T09:35:02.000Z"
}

List & get#

GET/v1/phone-numbers

Lists every number on the org, newest-first. Filter by agent_id or status.

Response · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "pn_5b8f0d21",
      "object": "phone_number",
      "e164": "+966920000123",
      "country": "SA",
      "agent_id": "ag_7Q2c51b84a07",
      "provider": "platform",
      "status": "active",
      "inbound": true,
      "outbound": true,
      "monthly_usd": 2.0,
      "per_min_usd": 0.015,
      "created_at": "2026-07-13T09:34:11.000Z"
    },
    {
      "id": "pn_a1c93e70",
      "object": "phone_number",
      "e164": "+966920000456",
      "country": "SA",
      "agent_id": "ag_7Q2c51b84a07",
      "provider": "sip",
      "status": "active",
      "inbound": true,
      "outbound": true,
      "monthly_usd": 0,
      "per_min_usd": 0,
      "created_at": "2026-07-13T09:35:02.000Z"
    }
  ],
  "has_more": false
}

GET/v1/phone-numbers/{id}

Returns the full phone-number object. Unknown or cross-org IDs return 404 not_found.

Attach to a different agent#

PATCH/v1/phone-numbers/{id}

Re-point a number at another agent by sending the new agent_id. The change is instant — the next inbound call is answered by the new agent. Nothing else about the number moves, and billing is unaffected.

Request

curl -X PATCH https://voice.whizztech.ai/v1/phone-numbers/pn_5b8f0d21 \
  -H "Authorization: Bearer $WHIZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "ag_1f0b74d9c3e2" }'

Release a number#

DELETE/v1/phone-numbers/{id}

Releasing detaches the number from its agent and returns 204 No Content. You can also release with POST /v1/phone-numbers and action: "release"plus the e164. A platform number stops billing the moment it's released; a BYO number simply detaches — the trunk stays yours.

Request

curl -X DELETE https://voice.whizztech.ai/v1/phone-numbers/pn_5b8f0d21 \
  -H "Authorization: Bearer $WHIZZ_KEY"

Fields#

Field	Type	Description
id	string	Stable identifier, prefixed pn_.
e164	string	The number in E.164 form, e.g. +966920000123.
country	string	ISO-2 country of the number, e.g. SA, AE, EG.
agent_id	string	The agent that answers and places calls on this number.
provider	string	`platform` for a number allocated or imported through us, or `twilio` · `telnyx` · `sip` for a bring-your-own trunk.
status	string	active · pending · released. Only active numbers route calls.
inbound	boolean	Whether the number accepts incoming calls.
outbound	boolean	Whether the number may be used as the caller ID for outbound calls.
monthly_usd	number	Monthly rental billed at cost — $2.00 for a platform number, $0 for BYO.
per_min_usd	number	Per-minute telephony billed at cost — $0.015 for a platform number, $0 for BYO (minutes run on your carrier).

NextWidget→