Phone Numbers

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, national, tollFree. The API also
                            # takes mobile; this SDK does not type it yet, so use REST for it.
    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.phone_number.id)            # pn_abc123
print(phone_number.phone_number.phone_number)  # +14155551234
print(phone_number.phone_number.status)        # active

Buying numbers requires a paid plan (402 paid_plan_required on Free). A paid plan includes one number at no charge, once per account: a US or Canadian number (a +1 number) costing $20 a month or less; is_free_eligible in search results marks the number that qualifies.

Some numbers require regulatory information before they can be used; the purchase checks the exact number before charging anything. The SDK does not send type or regulatoryRequirements yet: for those numbers use the REST flow in Regulatory Requirements, then poll the number’s regulatory status until it is approved. A sender can be assigned before or after approval.

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.retrieve("pn_abc123").phone_number

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
client.phone_numbers.update("pn_abc123", name="Marketing Line")

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

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

Release Phone Number

Release a phone number you no longer need:

client.phone_numbers.release("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

import zavudev

try:
    client.phone_numbers.purchase(phone_number="+14155551234")
except zavudev.APIStatusError as e:
    code = e.body.get("code") if isinstance(e.body, dict) else None
    if code == "insufficient_balance":
        print("Add funds to your account")
    elif code == "number_unavailable":
        print("Phone number is no longer available")
    elif code == "regulatory_compliance_required":
        print("This number needs regulatory information")

​Search Available Numbers

​Search Parameters

​Purchase a Phone Number

​List Phone Numbers

​Get Phone Number

​Update Phone Number

​Release Phone Number

​Response Types

​Phone Number Object

​Available Phone Number Object

​Error Handling

Search Available Numbers

Search Parameters

Purchase a Phone Number

List Phone Numbers

Get Phone Number

Update Phone Number

Release Phone Number

Response Types

Phone Number Object

Available Phone Number Object

Error Handling