Phone numbers API

Search, buy, assign, configure, and release the telephony numbers in your workspace. Reading is gated on agents.read; everything that changes a number needs phone_numbers.write.

The phone number object

{
  "id":            "uuid",
  "phone_number":  "+14165550123",
  "widget_id":     "uuid",
  "enabled":       true,
  "voice_enabled": true,
  "sms_enabled":   true,
  "friendly_name": "Main line",
  "number_type":   "local",
  "iso_country":   "CA",
  "monthly_cost_cents": 500
}

Search & buy

GET  /api/v1/rest/phone-numbers/search   ?country= &type= &area_code= &contains= &in_postal_code=
POST /api/v1/rest/phone-numbers
{
  "widget_id":    "uuid",          // the agent to attach it to
  "phone_number": "+14165550123"   // a search result; omit to auto-pick by country/type/area_code
}

Buying provisions the number with the carrier and wires its voice/SMS webhooks to the agent in one step (voice and SMS default on). Buying costs real money, billed monthly in credits. If the agent already has an active number you get a 409 — pass "force": true to add a second one deliberately.

List & get

GET /api/v1/rest/phone-numbers      ?widget_id= &include_released=true
GET /api/v1/rest/phone-numbers/:id

Update a number

PATCH /api/v1/rest/phone-numbers/:id
{
  "voice_enabled": true,
  "sms_enabled":   true,
  "friendly_name": "Service line",
  "enabled":       true
}

Enabling SMS also configures the number's inbound-SMS webhook with the carrier, fail-closed — if the carrier can't be configured the request fails rather than leaving a dead channel. PATCH does not change assignment — sending widget_id returns a 400 pointing you at the assign endpoint below.

Assign, reassign, unassign

POST /api/v1/rest/phone-numbers/:id/assign     { "widget_id": "uuid" }
POST /api/v1/rest/phone-numbers/:id/unassign

Assigning rewires the carrier webhooks to the new agent (a bare DB change would keep routing calls to the old one — this is why it's a dedicated endpoint). Reassigning a number whose current agent has an active campaign returns 409. Unassigning parks the number back in your pool.

Release a number

DELETE /api/v1/rest/phone-numbers/:id

Permanently releases the number back to the carrier and stops its monthly billing. Blocked with 409 while the assigned agent has an active campaign, and not available for admin-imported numbers.

Full schemas are in the OpenAPI reference.