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

```ruby theme={null}
result = client.phone_numbers.search_available(
  country_code: "US",
  type: "local",
  limit: 10
)

result.items.each do |number|
  puts "#{number.phone_number} #{number.locality} #{number.region}"
  puts "Monthly: #{number.pricing.monthly_price}"
  puts "Free eligible: #{number.pricing.is_free_eligible}"
end
```

### Search Parameters

```ruby 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

```ruby theme={null}
phone_number = client.phone_numbers.purchase(
  phone_number: "+14155551234",
  name: "Customer Support"
)

puts phone_number.id           # pn_abc123
puts phone_number.phone_number # +14155551234
puts 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

```ruby theme={null}
result = client.phone_numbers.list

result.items.each do |number|
  puts "#{number.id} #{number.phone_number} #{number.name}"
  puts "Status: #{number.status}"
  puts "Assigned to: #{number.sender_id}"
end

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

## Get Phone Number

```ruby theme={null}
number = client.phone_numbers.get(phone_number_id: "pn_abc123")

puts number.phone_number
puts number.name
puts number.capabilities
puts number.pricing.monthly_price
puts number.next_renewal_date
```

## Update Phone Number

Update the name or sender assignment:

```ruby 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: nil
)
```

## Release Phone Number

Release a phone number you no longer need:

```ruby 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>

## Error Handling

```ruby theme={null}
begin
  number = client.phone_numbers.purchase(
    phone_number: "+14155551234"
  )
rescue Zavudev::APIError => e
  case e.status
  when 402
    puts "Add funds to your account"
  when 404
    puts "Phone number is no longer available"
  else
    puts "Error: #{e.message}"
  end
end
```