How to Perform Phone Number and User Verification in PHP - PHP Phone Number Verification package blog

Introduction

Okay, we have established that phone number verification does not help me much on a personal level. Businesses that I work for, however, have an entirely different view on the importance of having quality contact phone numbers, and number verification is the first step in determining the quality of those numbers provided to them by their clients.

The New User

I do not think it is a stretch for me to say we have all experienced e-mail verification at some point in our adventures on the Internet. You may even have had to deal with verifying your own phone number to gain that 'special' access.

You know the situation, where after registration the company will send a text message to your phone with a secret code, which you then enter on their site and... you're in.

Companies that want to verify their users over the phone should try to determine that the phone number provided is valid while the user is still on the site and can correct any problems.

This is not because they should expect users to give false numbers. No, it is more likely that their users are like me... when I can't just enter 'Home', I have to try my best to remember what the heck my number is.

This is where the PHP Phone Number Verification package can come in handy. It uses a web service API provided by numverify.com which does more than just check the number against the latest databases. It will correct formatted phone numbers and return useful location and phone type information when available.

Here is our scenario... A new user has just submitted their registration form and we have saved the information they provided to our database. The next step in the process will be to verify their phone number.

You may be asking at this point, why their phone number? Can't I just use their e-mail address like most everyone else does? Sure you can, however if you have to be more certain of a persons identity, malicious users are more likely to have disposable e-mail accounts than disposable phone numbers. Think about it.

Our form could look something like this...

<form method="POST">
  <div>Please provide your phone number for verification</div>
  <div><input type="text" name="phoneNumber"></div>
  <div>
    Can this number receive SMS text message?
    <select name="sendSMS">
      <option value="yes">Yes</option>
      <option value="no">No</option>
    </select>
  </div>
  <div>
    <input type="hidden" name="formSubmitted" value="1">
    <input type="submit" name="submit" value="Submit">
  </div>
</form>

So, we have nicely asked our new user to supply their phone number for verification and whether they can receive text messages. They have entered their answers and submitted the form to our script for processing.

//include numverify class
include('numverify.class.php');
//instantiate the class
$numVerify = new numVerify();
if( $_REQUEST[ 'formSubmitted' ] ){
  //user has submitted the form
  $phoneNumber = $_REQUEST['phoneNumber'];
  $sendSMS = ( $_REQUEST['sendSMS'] == 'yes' ) ? true : false;
  if( !empty($phoneNumber) ){
    //user has provided a phone number
    $isValid = $numVerify->isValid($phoneNumber,'US');
    if( $isValid ){
      //phone number is valid
      $phoneNumber = $numVerify->response->number;
      $phoneLocation = $numVerify->response->location;
      $phoneCarrier = $numVerify->response->carrier;
      $phoneType = $numVerify->response->line_type;
      if( $sendSMS ){
        //user can receive text message
        if( $phoneType == 'mobile' ) {
          //it all looks good, save data and send verification text
        } else {
          //not a mobile phone, user must validate their submission
        }
      } else {
        //can't send text so queue for customer service contact
      }
    } elseif( !empty($numVerify->response->errorCode) ){
      if( $numVerify->response->errorCode == 211 ){
        //user did not provide a numeric phone number
      } else {
        //oops, we have an internal problem, emergency, emergency
      }
    } else {
      //phone number isn't valid, request user correct their number
    }
  } else {
    //no phone number provided, return to form
  }
}

If you have worked your way through the logic, you can see that we have really been able to give the number a good check. To get to the point we feel confident enough to say the number is a good number to use...

1) We first check that the user submitted a number.
2) We then check to make sure the number is valid.
3) We then use a clean, unformatted version of the number
4) If the user can receive a text, we make sure it is a mobile number
5) If the user can't receive a text, we let the humans handle the rest

Our example assumes that the number is from a user within the United States. The numverify service actually supports verification of phone numbers from 232 countries worldwide, so if you need to go international, the power is there.

The current user

Let us not forget that users will also change their information from time to time. If they change their validated phone number, it would be the best practice to do a complete verification on the new number. This would be the only way to ensure that the new number is a good number.

If you really aren't that worried about current users changing their phone number, and don't want to 'hassle' them with a full verification, at a minimum you should at least to check that the supplied number is a valid number. This will also allow you to store a clean, unformatted version of the new number. The logic for this simplified check could look something like this...

if( $_REQUEST[ 'formSubmitted' ] ){
  $phoneNumber = $_REQUEST[ 'phoneNumber' ];
  if( !empty($phoneNumber) ){
    $isValid = $numVerify->isValid($phoneNumber,'US');
    if( $isValid ){
      //number is valid, save data
      $phoneNumber = $numVerify->response->number;
      $phoneLocation = $numVerify->response->location;
      $phoneCarrier = $numVerify->response->carrier;
      $phoneType = $numVerify->response->line_type;
    } elseif ( !empty($numVerify->response->errorCode) ) {
      if( $numVerify->response->errorCode == 211 ) {
        //user did not provide a numeric phone number
      } else {
        //oops, we have an internal problem, emergency, emergency
      }
    } else {
      //phone number isn't valid, request user correct their number
    }
  } else {
    //no phone number provided, return to form
  }
}

Assuming that we instantiated the class using $numVerify as our object, the response object will be $numVerify->response.

The numverify error response

If there was an error, the response object will contain the following...

$numVerify->response->success - will be false
$numVerify->response->error - error object
$numVerify->response->error->code - the error code
$numVerify->response->error->type - string representation for the code
$numVerify->response->error->info - human readable description of error

The class will also assign these properties...

$numVerify->errorCode - the error code
$numVerify->errorText - human readable description of error

On an error, the following codes will be returned so that you can properly process the problem.

101 - invalid or missing api key in request
102 - inactive user account
103 - invalid api function requested
104 - usage limit exceeded
105 - current account does not support secure connection
210 - no phone number provided
211 - phone number is not numeric
310 - invalid 2 digit country code in request
404 - requested resource does not exist

The numverify success response

On success, the response object will contain the following...

$numVerify->response->valid - true or false valid number
$numVerify->response->number - clean, unformatted version of number
$numVerify->response->local_format - number dialed locally
$numVerify->response->international_format - number dialed internationally
$numVerify->response->country_code - 2 letter country code
$numVerify->response->country_name - full country name
$numVerify->response->location - local area, if available
$numVerify->response->carrier - carrier number is registered with
$numVerify->response->line_type - type of phone number

The following is a list of returned line types...

mobile - mobile phone
landline - land line (home/office) phone
special_services - police, fire, emergency
toll_free - toll free number
premium_rate - paid hotlines

Conclusion

Verifying user phone numbers will be the most common use in development projects, however you may need to set up a phone marketing campaign where you only want to cold call valid land lines. You may want to have an annual review of client contact numbers.

I am also sure that some company, somewhere, is going to need verification for some reason that has not even been thought up yet. This is the package and service for that.

If you liked this article or you have questions about phone number verification, post a comment here.