Phone Number

Phone number schemas manage the complete lifecycle of phone number acquisition from telephony providers: discovery of available inventory, purchase transactions, and provisioning into Phone Configurations.

Source: src/core/service-configuration/phone-number.schema.ts

---

BasePhoneNumberInfo

Common properties for available phone numbers from provider inventory.

Schema: BasePhoneNumberInfoSchema

Attributes

Attribute	Type	Required	Default	Description
friendlyName	string	Yes	—	Human-readable name for the number
phoneNumber	string	Yes	—	Phone number in E.164 format
lata	string | null	No	—	Local Access and Transport Area code
rateCenter	string	No	—	Rate center for billing/routing
region	string	No	—	State or province code
postalCode	string	No	—	Associated postal code
countryCode	string	Yes	—	ISO country code
capabilities	object	Yes	—	Voice, SMS, MMS capabilities
beta	boolean	Yes	—	Whether this is a beta number
numberType	enum	Yes	—	Type of phone number. One of LOCAL, TOLL_FREE, or MOBILE.

---

PhoneNumberPurchase

Phone number purchase transaction record.

Schema: PhoneNumberPurchaseSchema

Attributes

Attribute	Type	Required	Default	Description
id	string	—	—	Unique identifier for the purchase
friendlyName	string	Yes	—	Display name for the number
phoneNumber	string	Yes	—	Phone number in E.164 format
countryCode	string	Yes	—	ISO 3166-1 alpha-2 country code
chargedCredits	number	Yes	—	Amount charged for purchase
status	enum	No	PENDING	Current purchase status. One of PENDING, PROCESSING, COMPLETED, FAILED, or CANCELLED.
numberType	enum	No	LOCAL	Type of phone number. One of LOCAL, TOLL_FREE, or MOBILE.
statusDetails	string | null	No	—	Additional status information
completedAt	number | null	No	—	Completion timestamp
metadata	object | null	No	—	Additional purchase metadata
createdAt	number	—	—	Unix timestamp when created
updatedAt	number	—	—	Unix timestamp when last updated

---

PhoneNumberPricing

Pricing information for phone numbers.

Schema: PhoneNumberPricingSchema

Attributes

Attribute	Type	Description
number_type	enum	Type of phone number. One of LOCAL, TOLL_FREE, or MOBILE.
country	string	Full country name
countryCode	string	ISO country code
phoneNumberPrices	array	Array of pricing tiers
price	number	Final price
priceUnit	string	Unit of pricing (e.g., "per month")
currency	string	Currency code (default: "USD")

---

Example

Phone Number Purchase

{
  "id": "purchase_abc123",
  "friendlyName": "Main Support Line",
  "phoneNumber": "+12125551234",
  "countryCode": "US",
  "chargedCredits": 1500,
  "status": "COMPLETED",
  "numberType": "LOCAL",
  "completedAt": 1709856000000,
  "createdAt": 1709856000000,
  "updatedAt": 1709856000000
}

Available Phone Number

{
  "friendlyName": "New York Local",
  "phoneNumber": "+12125551234",
  "countryCode": "US",
  "capabilities": {
    "voice": true,
    "SMS": true,
    "MMS": false
  },
  "beta": false,
  "numberType": "LOCAL"
}

---

Create Schema

Schema	Description	Omits
CreatePhoneNumberPurchaseSchema	For initiating purchases	id, chargedCredits, status, createdAt, updatedAt, statusDetails, completedAt, metadata

---

Related

• Phone Configuration - Manages purchased phone numbers