> ## 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

> Search, purchase and assign phone numbers via the Zavu Python SDK. Manage SMS, WhatsApp and Voice numbers across countries with one API.

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, 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

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

<Info>
  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.
</Info>

<Info>
  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](/guides/phone-numbers/regulatory-requirements), then poll the number's regulatory status until it is `approved`. A sender can be assigned before or after approval.
</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.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:

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

```python theme={null}
client.phone_numbers.release("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}
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")
```