> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone Numbers

> Manage phone numbers with the Python SDK

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:

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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
```

<Info>
  Your first US phone number is free. The `is_free_eligible` field in search results indicates eligible numbers.
</Info>

## List Phone Numbers

```python theme={null}
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

```python theme={null}
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:

```python theme={null}
# 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:

```python theme={null}
client.phone_numbers.release(phone_number_id="pn_abc123")
```

<Warning>
  You cannot release a phone number assigned to a sender. Unassign it first.
</Warning>

## Response Types

### Phone Number Object

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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")
```