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.


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


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.


  • 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:
        # It relies on the twilio-ruby gem
        # The app responds to GET and POST at
        # and POST at
        require 'rubygems'
        require 'sinatra'
        require 'twilio-ruby'
        # display a nice little form to the user
        get '/search-numbers' do
          <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"/>

      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
          client =, 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?
            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>"
              out << '</body></html>'
              '<b>Sorry!</b> Twilio doesn\'t have any numbers available that match those constraints.'
          rescue StandardError => e
            '<b>Sorry!</b> ' + e.message + '.'

      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
          client =, auth_token)
          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 + '.'

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