v1

latestOpenAPI 3.0.02026-08-063524105.9 KB

Telephony - Phone Numbers

Buy a phone number

Purchase a phone number.

post/internal/telephony/phone-numbers/buy

Request body

workspaceIdstring uuid required

Workspace ID

numberstring required

Phone number to purchase

countryDialstring

Country dial code

type'inbound_outbound' | 'outbound_only'

Phone number type

addressBundleIdstring uuid

Address bundle for compliance

messagingProfileIdstring

Messaging profile ID

Example request

{
  "workspaceId": "789e4567-e89b-12d3-a456-426614174000",
  "number": "+14155551234",
  "countryDial": "+1",
  "type": "outbound_only"
}

Response

Phone number purchased

idstring uuid required

Unique identifier

workspaceIdstring uuid required

Workspace ID

numberstring required

Phone number in E.164 format

countryDialstring nullable required

Country dialing code

status'pending' | 'active' | 'payment_failed' | 'activation_failed' required

Phone number status

type'inbound_outbound' | 'outbound_only' required

Phone number type

engineIdstring nullable required

Voice engine ID

telephonyIdstring nullable required

Provider phone number ID

pricenumber nullable required

Monthly price in USD

purchasedAtstring date-time nullable required

Purchase timestamp

renewalAtstring date-time nullable required

Next renewal timestamp

dialsTodaynumber required

Dials today

dialsTotalnumber required

Total dials

availableboolean required

Available for use

deletedAtstring date-time nullable required

Soft delete timestamp

createdAtstring date-time required

Creation timestamp

updatedAtstring date-time required

Last update timestamp

Example response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "789e4567-e89b-12d3-a456-426614174000",
  "number": "+14155551234",
  "countryDial": "+1",
  "status": "active",
  "type": "outbound_only",
  "engineId": "asst_abc123",
  "telephonyId": "1234567890",
  "price": 1.5,
  "purchasedAt": "2025-12-11T12:00:00Z",
  "renewalAt": "2026-01-11T12:00:00Z",
  "available": true,
  "createdAt": "2025-12-11T12:00:00Z",
  "updatedAt": "2025-12-11T12:00:00Z"
}