Cleanse a Number with PhoneID

// note change this to the following if using npm package: require('telesignsdk);
var TeleSignSDK = require('telesignsdk');

const customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"; // Todo: find in portal.telesign.com
const apiKey = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="; // Todo: find in portal.telesign.com
const rest_endpoint = "https://rest-api.telesign.com"; // Todo: Enterprise customer, change this!
const timeout = 10*1000; // 10 secs

const client = new TeleSignSDK( customerId,
    apiKey,
    rest_endpoint,
    timeout // optional
    // userAgent
);

const phoneNumber = "Your test phone number with no special characters or spaces.";

console.log("## PhoneIDClient.phoneID ##");

function messageCallback(error, responseBody) {
    if (error === null) {
        console.log(`PhoneID response for phone number: ${phoneNumber} ` +
            `=> code: ${responseBody['status']['code']}, ` +
            `description: ${responseBody['status']['description']}`);

        if (responseBody['status']['code'] === 200) {
            const cc = responseBody['numbering']['cleansing']['call']['country_code'];
            const pn = responseBody['numbering']['cleansing']['call']['phone_number'];
            console.log("Cleansed phone number has country code $cc and phone number is $pn.")
        }
    } else {
        console.error("Unable to get PhoneID. $error");
    }
}

client.phoneid.phoneID(messageCallback, phoneNumber);

This quick start describes how to use TeleSign SDKs to cleanse a phone number using PhoneID. Phone number cleansing corrects common formatting issues in submitted phone numbers. After phone number cleansing, PhoneID takes the cleansed number and returns details about it such as phone type, location, and carrier information in a JSON response. You can use this information to make choices about what to do with the phone number.

This quick start includes the following sections:

Requirements

For this quick start, the following is required:

  • customer ID - obtain from your account by logging in to portal.telesign.com (referred to as customer_id/customerId in this document)
  • API key - obtain from your account by logging in to portal.telesign.com (referred to as api_key/apiKey in this document)
  • SDK - Access to TeleSign’s GitHub repository for your selected language:
  • Node.js
  • Java
  • Python
  • Ruby
  • PHP
  • C#
  • Language Version
  • Node.js - 6+
  • Java - 7+
  • Python - 2.7+
  • Ruby - 2+
  • PHP - 5.6+
  • C# - 4.5+
  • Verified Phone Number - To use TeleSign’s free trial, you must verify a phone number before using it.
NOTE:

If you do not have a customer ID, sign up for TeleSign’s Free Trial.

Install the SDK

  1. Obtain your customer ID and API key.
  2. Log in to GitHub and navigate to the SDK in the language of your choice:
  1. Download or clone the repository. If you download it, extract the repository from the .ZIP file.
  2. To install the SDK for use, do the following:

Cleanse a Number with PhoneID

This section explains how to cleanse a number with PhoneID. The sample code provided earlier is broken out into pieces and explained below.

In this code sample, you provide your customer ID and API key to authenticate yourself with TeleSign. You insert a phone number to cleanse. For the purpose of the example, you can insert your phone number with proper formatting, and this sample code will make the phone number incorrect by adding an extra digit. You create a PhoneIdClient object and use the phoneid method to cleanse the incorrect phone number. To see what it looks like cleansed, you then use a print statement that shows you the cleansed phone number and what the original phone number was.

  1. Begin by adding statements for including the appropriate part of the TeleSign SDK and any additional language specific functions you may need.
npm install telesignsdk -save
  1. Insert values for each of the items from customer_id through to phone_number.
  • customer_id/customerId - Your TeleSign assigned customer ID, available in your account information in the portal.
  • api_key/apiKey - Your TeleSign assigned API key, available in your account information in the portal.
  • phone_number/phoneNumber - The phone number you want to use for the example. If you are doing a free trial, the phone number must be verified (verifying the number is not required if you are a paying customer). When you provide the number, it should be a string with no spaces or special characters. Include the complete number. For example, if you are doing a phone number for America, you would include the country code and the area code with the number. For example 16505551212.
const customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"; // Todo: find in portal.telesign.com
const apiKey = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="; // Todo: find in portal.telesign.com
const rest_endpoint = "https://rest-api.telesign.com"; // Todo: Enterprise customer, change this!
const timeout = 10*1000; // 10 secs

const client = new TeleSignSDK( customerId,
    apiKey,
    rest_endpoint,
    timeout // optional
    // userAgent
);

const phoneNumber = "Your test phone number with no special characters or spaces.";
  1. This code sets up an example incorrect phone number so you can see how cleansing with PhoneID works. This step does not apply to node.js.
//Step does not apply to node.js
  1. Instantiate a PhoneIdClient object and pass it your customer ID and your API key. For node.js, you use this step to set up a function that will log, check, and cleanse the phone number it pulls from responseBody.
console.log("## PhoneIDClient.phoneID ##");

function messageCallback(error, responseBody) {
    if (error === null) {
        console.log(`PhoneID response for phone number: ${phoneNumber} ` +
            `=> code: ${responseBody['status']['code']}, ` +
            `description: ${responseBody['status']['description']}`);

        if (responseBody['status']['code'] === 200) {
            const cc = responseBody['numbering']['cleansing']['call']['country_code'];
            const pn = responseBody['numbering']['cleansing']['call']['phone_number'];
            console.log("Cleansed phone number has country code $cc and phone number is $pn.")
        }
    } else {
        console.error("Unable to get PhoneID. $error");
    }
}
  1. Use PhoneID to check and cleanse the incorrect phone number you created earlier. For node.js, you use this step to set up your phoneID client using the function you created in the last step. Everything should run and you will get back a response containing your cleansed phone number and the original phone number. The messageCallback function will print details about what happened.
client.phoneid.phoneID(messageCallback, phoneNumber);
  1. Use two print statements to check the results of the cleansing procedure on the incorrect phone number. The first print statement explains what the cleansed phone number is and displays the JSON response for the cleansed number. The second print statement shows the original phone number and displays the JSON response for the original phone number. For node.js, you already set up the function that will check results.
//Step does not apply for node.js
  1. If everything works, you send an incorrect phone number to PhoneID for cleansing, and you get back a response containing your cleansed phone number and the original phone number.

Code it Without the SDK

If you want to write all your own code, you will need to handle authentication yourself. You’ll need the following documents: