Get Started

Phone Number Search API

The Twilio REST API allows you to perform advanced searches within Twilio's available phone number inventory. You can search for available numbers that match a specific pattern, are in a specific geographic area and more. Once you've found a number you'd like to buy you simply request that Twilio provision it for your account.

Concepts

This HowTo demonstrates finding an available phone number using the REST API's AvailablePhoneNumbers resource and then provisioning that number through the IncomingPhoneNumbers resource.

Usage

We set up a web form that lets a user search for and buy a new Twilio number. The user can choose various selection criteria and browse Twilio's matching available phone numbers. Once a suitable number is found, the user simply clicks "BUY" to purchase it.

Overview

  • 1

    • We first present a form to the user that lets him or her enter criteria to search by

      • howtos/search-and-buy/search-and-buy.rb 
        # Code is designed for Sinatra, a lightweight ruby framework:
# http://www.sinatrarb.com/
# It relies on the twilio-ruby gem http://github.com/twilio/twilio-ruby
# The app responds to GET and POST at http://yourapp.com/search-numbers
# and POST at http://yourapp.com/buy-number
require 'rubygems'
require 'sinatra'
require 'twilio-ruby'

# display a nice little form to the user
get '/search-numbers' do
<<EOF
  <html><head><title>Find a Twilio number to buy</title></head>
  <body><h3>Find a Twilio number to buy</h3>
  <form method="POST">
    <label>near US postal code (e.g. 94117): </label><input type="text" size="4" name="in_postal_code"/><br/>
    <label>near this other number (e.g. +4156562345): </label><input type="text" size="7" name="near_number"/><br/>
    <label>matching this pattern (e.g. 415***EPIC): </label><input type="text" size="7" name="contains"/><br/>
    <input type="submit" value="SEARCH"/>
  </form>
  </body></html>
EOF
end

      We set up three form fields: one for searching for numbers within a postal code, one for searching for numbers near another number, and one for choosing an arbitrary pattern to search by.

  • 2

    • We take the user's criteria and search for available phone numbers that match

      • howtos/search-and-buy/search-and-buy.rb 
        post '/search-numbers' do
  account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
  auth_token = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY'
  
  client = Twilio::REST::Client.new(account_sid, auth_token)

  search_params = {}
  %w[in_postal_code near_number contains].each do |p|
    search_params[p] = params[p] unless params[p].nil? || params[p].empty?
  end

  begin
    local_numbers = client.account.available_phone_numbers.get('US').local
    numbers = local_numbers.list(search_params)
  
    unless numbers.empty?
      out = '<html><head><title>Choose a number</title></head><body><h3>Choose a number</h3>'
      numbers.each do |number|
        out << "<form method='POST' action='/buy-number'>"
        out << "<label>#{number.friendly_name}</label>"
        out << "<input type='hidden' name='PhoneNumber' value='#{number.phone_number}' />"
        out << "<input type='submit' value='BUY' /></form>"
      end
      out << '</body></html>'
    else
      '<b>Sorry!</b> Twilio doesn\'t have any numbers available that match those constraints.'
    end
  rescue StandardError => e
    '<b>Sorry!</b> ' + e.message + '.'
  end
end

      We make a GET request to the US Local AvailablePhoneNumbers list resource. If we find any numbers that match, we return a list to the user so that he or she can select one to buy.

  • 3

    • When the user clicks "BUY", POST the selected number to Twilio

      • howtos/search-and-buy/search-and-buy.rb 
        post '/buy-number' do
  account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
  auth_token = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY'
  
  client = Twilio::REST::Client.new(account_sid, auth_token)

  begin
  number = client.account.incoming_phone_numbers.create(
                   :phone_number => params[:PhoneNumber])
  
    '<b>Success!</b> You now own the number <b>' + number.phone_number + '</b>.'
  rescue StandardError => e
    '<b>Sorry!</b> ' + e.message + '.'
  end
end

      Here we take the selected phone number and POST it to the IncomingPhoneNumbers list resource to buy it.