Skip to main content
Phone numbers are required for sending SMS and WhatsApp messages. You can search for available numbers, purchase them, and manage them through the API.

​
Search Available Numbers

Find phone numbers available for purchase: 
result = client.phone_numbers.search_available(
    country_code="US",
    type="local",
    limit=10
)

for number in result.items:
    print(number.phone_number, number.locality, number.region)
    print("Monthly:", number.pricing.monthly_price)
    print("Free eligible:", number.pricing.is_free_eligible)

​
Search Parameters

result = client.phone_numbers.search_available(
    country_code="US",      # Required: Two-letter country code
    type="local",           # Optional: local, mobile, tollFree
    contains="555",         # Optional: Pattern to search for
    limit=20                # Optional: Max results (default: 10, max: 50)
)

​
Purchase a Phone Number

phone_number = client.phone_numbers.purchase(
    phone_number="+14155551234",
    name="Customer Support"
)

print(phone_number.id)            # pn_abc123
print(phone_number.phone_number)  # +14155551234
print(phone_number.status)        # active
Your first US phone number is free. The is_free_eligible field in search results indicates eligible numbers.

​
List Phone Numbers

result = client.phone_numbers.list()

for number in result.items:
    print(number.id, number.phone_number, number.name)
    print("Status:", number.status)
    print("Assigned to:", number.sender_id)

# With filters
result = client.phone_numbers.list(
    status="active",
    limit=50,
    cursor="cursor_xxx"
)

​
Get Phone Number

number = client.phone_numbers.get(phone_number_id="pn_abc123")

print(number.phone_number)
print(number.name)
print(number.capabilities)
print(number.pricing.monthly_price)
print(number.next_renewal_date)

​
Update Phone Number

Update the name or sender assignment: 
# Update name
number = client.phone_numbers.update(
    phone_number_id="pn_abc123",
    name="Marketing Line"
)

# Assign to a sender
number = client.phone_numbers.update(
    phone_number_id="pn_abc123",
    sender_id="snd_xyz789"
)

# Unassign from sender
number = client.phone_numbers.update(
    phone_number_id="pn_abc123",
    sender_id=None
)

​
Release Phone Number

Release a phone number you no longer need: 
client.phone_numbers.release(phone_number_id="pn_abc123")
You cannot release a phone number assigned to a sender. Unassign it first.

​
Response Types

​
Phone Number Object

class PhoneNumber:
    id: str
    phone_number: str
    name: Optional[str]
    capabilities: List[str]        # ["sms", "voice", "mms"]
    status: Literal["active", "suspended", "pending"]
    sender_id: Optional[str]
    pricing: PhoneNumberPricing
    next_renewal_date: Optional[str]
    created_at: str
    updated_at: Optional[str]

class PhoneNumberPricing:
    monthly_price: float
    upfront_cost: int
    monthly_cost: int
    is_free_number: bool

​
Available Phone Number Object

class AvailablePhoneNumber:
    phone_number: str
    friendly_name: Optional[str]
    locality: Optional[str]
    region: Optional[str]
    capabilities: PhoneNumberCapabilities
    pricing: AvailablePricing

class PhoneNumberCapabilities:
    sms: bool
    voice: bool
    mms: bool

class AvailablePricing:
    monthly_price: float
    upfront_price: float
    is_free_eligible: bool

​
Error Handling

from zavu import ZavuError

try:
    number = client.phone_numbers.purchase(
        phone_number="+14155551234"
    )
except ZavuError as e:
    if e.code == "insufficient_balance":
        print("Add funds to your account")
    elif e.code == "not_found":
        print("Phone number is no longer available")