How to Verify Phone Numbers in Ruby with the Lookup API

Time to read: 3 minutes

April 23, 2015
Written by
Greg Baugues
Twilion

Twilio Lookup

Twilio Lookup is a REST API that can:

  • Verify that a phone number exists
  • Format any international phone number into its local standard
  • Determine if a phone number is a cell phone, VOIP or landline
  • Discover information about a phone number’s carrier

In this tutorial we’ll use the Twilio Ruby gem to get phone number data from the Lookup API in just a few lines of code.

To start, sign up for free Twilio account.

try-twilio

Getting Started

Install the Twilio gem:

gem install twilio-ruby

Grab your Account SID and Auth Token from the Twilio dashboard:

twilio-credentials

In your code:

  • require the gem
  • set constants for our credentials (you’ll want to use environment variables in a real app)
  • create a Lookup Client

 

require 'twilio-ruby'
TWILIO_ACCOUNT_SID = 'REPLACEME!'
TWILIO_AUTH_TOKEN = 'REPLACEME!'
lookup_client = Twilio::REST::LookupsClient.new(TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN)

Armed with a REST client, you’re ready to lookup some numbers.

Valid Phone Numbers

Let’s start by looking up a valid phone number.

If we punch the number my dog uses to send selfies into the Lookup homepage, we’d see that a successful Lookup returns a JSON object:

lookup-number

Here’s how you do that lookup in Ruby:

response = lookup_client.phone_numbers.get('13123131434')

If the phone number is valid, the gem converts the JSON attributes into methods on the response object:

response.country_code  # => "US"
response.phone_number # => "+13123131434"
response.national_format # => "(312) 313-1434"
response.url #=> "https://lookups.twilio.com/v1/PhoneNumber/+13123131434"

This lookup is free, but only has information about the number itself. If you’d like to get information about the carrier, it’ll cost you half a penny ($0.005). This is especially useful for determining if a phone number is capable of receiving an SMS/MMS.

To perform a carrier lookup, simply add an additional parameter:

response = lookup_client.phone_numbers.get('+13123131434', type: 'carrier')

Then you can access carrier data like this:

response.carrier['name']
response.carrier['mobile_country_code']
response.carrier['mobile_network_code']
response.carrier['type']
response.carrier['error_code']

Try it with your own phone number and see what happens.

Invalid Phone Numbers

Before we talk about invalid phone numbers, let’s talk about bit about REST APIs.

Imagine you have a RESTful web app that serves as an online bookstore. The unique id for each book is a sluggified version of its title. For instance, to view the details of Bob Martin’s The Clean Coder (great book!), we would do:

GET http://mybookstore.com/books/the-clean-coder

Now, what happens if we try to GET the details of a book that doesn’t exist? To the best of my knowledge no one’s written a book called The Dirty Coder (though someone certainly should). So if we try this:

GET http://mybookstore.com/books/the-dirty-coder

We’ll get a 404 because the book’s not found, right?

Twilio’s Lookup is a REST API. Conceptually, you can think of it as an online phonebook with with phone numbers serving as the unique ID. When a phone number is not found, we get a 404.

We can see this as well on the Lookup homepage:

invalid-phone-lookup

When the Twilio gem encounters a 404, it will throw an exception. Thus, whenever we’re using the Lookup API to validate phone numbers, we need to catch the exception and check to see if the error matches Twilio’s “Not Found” error code: 20404.

To write a function that validates a phone number, we need to:

  • Initiate a lookup client
  • Look up the phone number and try to access an attribute on it
  • If that works successfully, return true
  • If it raises an exception, return false if the error is a 20404 (otherwise just raise the exception as normal)

 

def valid?(phone_number)
  lookup_client = Twilio::REST::LookupsClient.new(TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN)
  begin
    response = lookup_client.phone_numbers.get(phone_number)
    response.phone_number #if invalid, throws an exception. If valid, no problems.
    return true
  rescue => e
    if e.code == 20404
      return false
    else
      raise e
  end
end

Try it out with a real and fake number and see what happens :

valid?('13133141434') # => true
valid?('15558675309') # => false

 

What we learned

Let’s recap:

  1. Twilio Lookup is a REST API phone book. Lookup doesn’t serve to answer the question “Does this number exist?”. It serves to give data about valid phone numbers and returns a 404 when a phone number is not found — just as a REST API should.
  2. The Twilio gem throws an exception on 404s. If you can successfully retrieve information about a phone number, you know the phone number is valid. If Ruby throws an exception when you try to lookup a phone number, chances are that the phone number is invalid (but check the error code just to be sure).

We’d love to hear what you do with the Lookup API. The most obvious use cases for Lookup are phone number validation, phone number formatting, and determining if a phone number can receive text messages. That said, like most of our products, the coolest use of this API is probably going to be something that a developer like you dreams up that we never even considered.

We can’t wait to see what you come up with.

If you enjoyed this post, you may want to follow me on twitter. If you have any questions, drop me an email at gb@twilio.com.

Related Posts

Related Resources

A newspaper article

Twilio Docs

From APIs to SDKs to sample apps

API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.
An Open book

Resource Center

The latest ebooks, industry reports, and webinars

Learn from customer engagement experts to improve your own communication.
User group reactions

Ahoy

Twilio's developer community hub

Best practices, code samples, and inspiration to build communications and digital engagement experiences.