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
)

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

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"
)

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

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

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: 
# 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: 
client.phone_numbers.release(phone_number_id: "pn_abc123")
You cannot release a phone number assigned to a sender. Unassign it first.

​
Error Handling

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