Phone ID - Tutorial: Cleanse a number with Phone ID

This tutorial walks you step-by-step through how to write code that makes a request to Telesign Phone ID using an SDK to cleanse a phone number. Phone number cleansing corrects common formatting issues in submitted phone numbers.

Full sample code is available at the end of this tutorial.

This code will take your test phone number, add an extra digit to make it invalid, and send it to Phone ID to cleanse. It then takes the cleansed phone number from the response and prints it to the console.

📘
NOTE:
This tutorial applies only to self-service accounts, not full-service accounts.

Before you begin

Make sure you have the following before you begin:

Authentication credentials: Your Customer ID and API Key. If you need help finding these items, go to the support article How do I find my Customer ID and API Key?
SDK - Download the SDK from 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+
Phone number - The phone number you want to cleanse. If you are a self-service customer and have not added money to your account yet, you need to first get the phone number verified by Telesign by adding it to your list of Test Numbers.

Install the SDK

Node.js: Browse / Download
Java: Browse / Download
Python: Browse / Download
Ruby: Browse / Download
PHP: Browse / Download
C#: Browse / Download

Download or clone the repository. If you download it, extract the repository from the .ZIP file.
To install the SDK for use, do the following:

npm install telesignsdk -save

compile 'com.telesign:telesign:[current_version]'

<dependency>
    <groupId>com.telesign</groupId>
    <artifactId>telesign</artifactId>
    <version>[current_version]</version>
</dependency>

# From a terminal run:
pip install telesign

# From a terminal run:
gem install telesign

# From a terminal run: 
composer require telesign/telesign

/* Add this to your packages.config file. */
<package id="Telesign" version="(insert latest version)" targetFramework="(insert framework)" />

Cleanse a number with Phone ID

Include the appropriate part of the Telesign SDK and any additional language specific functions you may need.

npm install telesignsdk -save

package com.telesign.example.phoneid;

import com.telesign.PhoneIdClient;
import com.telesign.RestClient;

from __future__ import print_function
from telesign.phoneid import PhoneIdClient

#If you are working with a version of Python 3, you do not need the first import #statement (`from __future__ import print_function`).

require 'telesign'

<?php
require __DIR__ . "/../../vendor/autoload.php";
use telesign\sdk\phoneid\PhoneIdClient;

using System;

Insert values for each of the items from customer_id through to phone_number.

customer_id/customerId - Your Telesign-assigned customer ID.
api_key/apiKey - Your Telesign-assigned API key.
phone_number / phoneNumber - The test phone number to cleanse. Include this as a string with no spaces or special characters. Include the complete number; for example, for a US phone number, you would include the country code and the area code with the number, like this: 16505551212.

const customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"; 
const apiKey = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==; 
const rest_endpoint = "https://rest-api.telesign.com";
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.";

public class Cleansing {

    public static void main(String[] args) {

        String customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
        String apiKey = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
        String phoneNumber = "Your test phone number with no special characters or spaces.";

customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
api_key = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
phone_number = "Your test phone number with no special characters or spaces."

customer_id = 'FFFFFFFF-EEEE-DDDD-1234-AB1234567890'
api_key = 'EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=='
phone_number = 'Your test phone number with no special characters or spaces.'

$customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
$api_key = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
$phone_number = "Your test phone number with no special characters or spaces.";

namespace Telesign.Example.PhoneId
{
    class Cleansing
    {
        static void Main(string[] args)
        {
            string customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
            string apiKey = "EXAMPLEABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

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

This code adds an extra digit to the number to make it invalid. This step does not apply to Node.js.

//Step does not apply to node.js

        String extraDigit = "0";
        String incorrectPhoneNumber = String.format("%s%s", phoneNumber, extraDigit);

extra_digit = "0"
incorrect_phone_number = "{}{}".format(phone_number, extra_digit)

extra_digit = '0'
incorrect_phone_number = "#{phone_number}#{extra_digit}"

$extra_digit = "0";
$incorrect_phone_number = "$phone_number$extra_digit";

            string extraDigit = "0";
            string incorrectPhoneNumber = string.Format("{0}{1}", phoneNumber, extraDigit);

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");
    }
}

        try {
        PhoneIdClient phoneIdClient = new PhoneIdClient(customerId, apiKey);

data = PhoneIdClient(customer_id, api_key)

phoneid_client = Telesign::PhoneIdClient.new(customer_id, api_key)

$data = new PhoneIdClient($customer_id, $secret_key);

            try
            {
                PhoneIdClient phoneIdClient = new PhoneIdClient(customerId, apiKey);

Use Phone ID 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);

            RestClient.TelesignResponse telesignResponse = phoneIdClient.phoneid(incorrectPhoneNumber, null);

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

            if (telesignResponse.ok) {
                System.out.println(String.format("Cleansed phone number has country code %s and phone number is %s.",
                        telesignResponse.json.getAsJsonObject("numbering").getAsJsonObject("cleansing").getAsJsonObject("call").get("country_code").getAsString(),
                        telesignResponse.json.getAsJsonObject("numbering").getAsJsonObject("cleansing").getAsJsonObject("call").get("phone_number").getAsString()));

                System.out.println(String.format("Original phone number was %s.",
                        telesignResponse.json.getAsJsonObject("numbering").getAsJsonObject("original").get("complete_phone_number").getAsString()));
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

if response.ok:
    print("Cleansed phone number has country code {} and phone number is {}.".format(
        response.json['numbering']['cleansing']['call']['country_code'],
        response.json['numbering']['cleansing']['call']['phone_number']))

    print("Original phone number was {}.".format(
        response.json['numbering']['original']['complete_phone_number']))

if response.ok
    puts 'Cleansed phone number has country code %s and phone number is %s.' %
        [response.json['numbering']['cleansing']['call']['country_code'],
        response.json['numbering']['cleansing']['call']['phone_number']]

    puts 'Original phone number was %s.' %
        [response.json['numbering']['original']['complete_phone_number']]
end

if ($response->ok) {
  printf("Cleansed phone number has country code %s and phone number is %s.",
  $response->json['numbering']['cleansing']['call']['country_code'],
  $response->json['numbering']['cleansing']['call']['phone_number']);
  printf("Original phone number was %s.",
  $response->json['numbering']['original']['complete_phone_number']);
}

                if (telesignResponse.OK)
                {
                    Console.WriteLine(string.Format("Cleansed phone number has country code {0} and phone number is {1}.",
                        telesignResponse.Json["numbering"]["cleansing"]["call"]["country_code"],
                        telesignResponse.Json["numbering"]["cleansing"]["call"]["phone_number"]));

                    Console.WriteLine(string.Format("Original phone number was {0}.",
                            telesignResponse.Json["numbering"]["original"]["complete_phone_number"]));
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e);
            }

            Console.WriteLine("Press any key to quit.");
            Console.ReadKey();
        }
    }
}

If everything works, you send an incorrect phone number to Phone ID for cleansing, and you get back a response containing your cleansed phone number and the original phone number.

Sample code

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

const customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"; 
const apiKey = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="; 
const rest_endpoint = "https://rest-api.telesign.com";
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(`Phone ID 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);

package com.telesign.example.phoneid;

import com.telesign.PhoneIdClient;
import com.telesign.RestClient;

public class Cleansing {

    public static void main(String[] args) {

        String customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
        String apiKey = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
        String phoneNumber = "Your test phone number with no special characters or spaces.";

        String extraDigit = "0";
        String incorrectPhoneNumber = String.format("%s%s", phoneNumber, extraDigit);

        try {
            PhoneIdClient phoneIdClient = new PhoneIdClient(customerId, apiKey);
            RestClient.TelesignResponse telesignResponse = phoneIdClient.phoneid(incorrectPhoneNumber, null);

            if (telesignResponse.ok) {
                System.out.println(String.format("Cleansed phone number has country code %s and phone number is %s.",
                        telesignResponse.json.getAsJsonObject("numbering").getAsJsonObject("cleansing").getAsJsonObject("call").get("country_code").getAsString(),
                        telesignResponse.json.getAsJsonObject("numbering").getAsJsonObject("cleansing").getAsJsonObject("call").get("phone_number").getAsString()));

                System.out.println(String.format("Original phone number was %s.",
                        telesignResponse.json.getAsJsonObject("numbering").getAsJsonObject("original").get("complete_phone_number").getAsString()));
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

from __future__ import print_function
from telesign.phoneid import PhoneIdClient

customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
api_key = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
phone_number = "Your test phone number with no special characters or spaces."

extra_digit = "0"
incorrect_phone_number = "{}{}".format(phone_number, extra_digit)

data = PhoneIdClient(customer_id, api_key)
response = data.phoneid(incorrect_phone_number)

if response.ok:
    print("Cleansed phone number has country code {} and phone number is {}.".format(
        response.json['numbering']['cleansing']['call']['country_code'],
        response.json['numbering']['cleansing']['call']['phone_number']))

    print("Original phone number was {}.".format(
        response.json['numbering']['original']['complete_phone_number']))

require 'telesign'

customer_id = 'FFFFFFFF-EEEE-DDDD-1234-AB1234567890'
api_key = 'EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=='
phone_number = 'Your test phone number with no special characters or spaces.'

extra_digit = '0'
incorrect_phone_number = "#{phone_number}#{extra_digit}"

phoneid_client = Telesign::PhoneIdClient.new(customer_id, api_key)
response = phoneid_client.phoneid(incorrect_phone_number)

if response.ok
    puts 'Cleansed phone number has country code %s and phone number is %s.' %
        [response.json['numbering']['cleansing']['call']['country_code'],
        response.json['numbering']['cleansing']['call']['phone_number']]

    puts 'Original phone number was %s.' %
        [response.json['numbering']['original']['complete_phone_number']]
end

<?php
require __DIR__ . "/../../vendor/autoload.php";
use telesign\sdk\phoneid\PhoneIdClient;
$customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
$api_key = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
$phone_number = "Your test phone number with no special characters or spaces.";
$extra_digit = "0";
$incorrect_phone_number = "$phone_number$extra_digit";
$data = new PhoneIdClient($customer_id, $api_key);
$response = $data->phoneid($incorrect_phone_number);
if ($response->ok) {
  printf("Cleansed phone number has country code %s and phone number is %s.",
  $response->json['numbering']['cleansing']['call']['country_code'],
  $response->json['numbering']['cleansing']['call']['phone_number']);
  printf("Original phone number was %s.",
  $response->json['numbering']['original']['complete_phone_number']);
}

using System;

namespace Telesign.Example.PhoneId
{
    class Cleansing
    {
        static void Main(string[] args)
        {
            string customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
            string apiKey = "EXAMPLEABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

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

            string extraDigit = "0";
            string incorrectPhoneNumber = string.Format("{0}{1}", phoneNumber, extraDigit);

            try
            {
                PhoneIdClient phoneIdClient = new PhoneIdClient(customerId, apiKey);
                RestClient.TelesignResponse telesignResponse = phoneIdClient.PhoneId(incorrectPhoneNumber);

                if (telesignResponse.OK)
                {
                    Console.WriteLine(string.Format("Cleansed phone number has country code {0} and phone number is {1}.",
                        telesignResponse.Json["numbering"]["cleansing"]["call"]["country_code"],
                        telesignResponse.Json["numbering"]["cleansing"]["call"]["phone_number"]));

                    Console.WriteLine(string.Format("Original phone number was {0}.",
                            telesignResponse.Json["numbering"]["original"]["complete_phone_number"]));
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e);
            }

            Console.WriteLine("Press any key to quit.");
            Console.ReadKey();
        }
    }
}

📘NOTE:

Before you begin

Install the SDK

Cleanse a number with Phone ID

Sample code

📘
NOTE: