Skip to main content
The Phone Number object contains information about a phone number, including its assigned agent and status.

​
Properties

​
phone_number_id
string
required
Unique identifier (UUID) for internal reference.
​
phone_number
string
required
Phone number in E.164 format. This is the primary identifier.Examples:
  • US: +15551234567
  • Israel: +972501234567
​
phone_number_pretty
string
required
Human-readable formatted phone number.Examples:
  • US: (555) 123-4567
  • Israel: 050-123-4567
​
display_name
string
Custom display name for the phone number. null if not set.
​
account
object
Account that owns the phone number.
​
agent
object
Assigned agent. null if no agent is assigned.
​
status
string
required
Phone number status:
StatusDescription
activeAgent is assigned and calls can be received
unassignedNo agent assigned, calls will fail
suspendedPhone number is temporarily disabled
​
created_at
string
required
ISO 8601 timestamp when the phone number was added.

​
Example

{
  "phone_number_id": "550e8400-e29b-41d4-a716-446655440000",
  "phone_number": "+15551234567",
  "phone_number_pretty": "(555) 123-4567",
  "display_name": "Main Support Line",
  "account": {
    "id": "550e8400-e29b-41d4-a716-446655440099",
    "name": "Acme Corp"
  },
  "agent": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Customer Support Agent",
    "version": 3
  },
  "status": "active",
  "created_at": "2026-01-15T10:30:00Z"
}