Phone ID - Tutorial: Check phone type to block VoIP

This tutorial walks you step-by-step through how to write code that makes a request to Telesign Phone ID using an SDK to identify voice over internet protocol (VoIP) numbers, so you can block them.

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

📘

NOTE:

This tutorial applies only to self-service accounts, not Enterprise accounts.

📘

Why block VoIP numbers?

VOIP numbers are cheap, easy to buy in bulk, and can easily be used by a fraudster to sign up for an account that requires a phone number as part of registration. After signup, they may abuse promotions and bonuses, spam other users, create fake likes, comments, or product reviews, sell fake/bulk accounts, and engage in other similar fraudulent activities. Blocking VOIP numbers can be a key part of securing your account registration process.

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:
  • Language Version
    • Node.js - 6+
    • Java - 7+
    • Python - 2.7+
    • Ruby - 2+
    • PHP - 5.6+
    • C# - 4.5+
  • Phone number - A VoIP phone number controlled by you, that you want to use for this tutorial. 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

  1. Log in to GitHub and choose the SDK in your preferred language:
  1. Download or clone the repository. If you download it, extract the repository from the .ZIP file.
  2. To install the SDK, 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)" />

Check phone type

  1. Include the appropriate part of the Telesign SDK and any additional language specific functions you may need.
// note change this to the following if using npm package: require('telesignsdk);
const TeleSignSDK = require('../../src/TeleSign');
//var TeleSignSDK = require('telesignsdk');
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;
  1. Insert values for each of the items from customer_id/customerId through phone_number/phoneNumber.
  • 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 purchased from TeleSign in TelePortal that you want to use. When you provide the number, it should be 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"; // 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";
const timeout = 10*1000; // 10 secs

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

const phoneNumber = "Test phone number with no special characters or spaces goes here.";
public class CheckPhoneTypeToBlockVoip {

    public static void main(String[] args) {

        String customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
        String apiKey = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

        String phoneNumber = "Test phone number with no special characters or spaces goes here.";
        String phoneTypeVoip = "5";
customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
api_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="

phone_number = "Test phone number with no special characters or spaces goes here."
phone_type_voip = "5"
customer_id = 'FFFFFFFF-EEEE-DDDD-1234-AB1234567890'
api_key = 'EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=='

phone_number = 'Test phone number with no special characters or spaces goes here.'
phone_type_voip = '5'
$customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
$api_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
$phone_number = "Test phone number with no special characters or spaces goes here.";
$phone_type_voip = "5";
namespace Telesign.Example.PhoneId
{
    class CheckPhoneTypeToBlockVoip
    {
        static void Main(string[] args)
        {
            string customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
            string apiKey = "EXAMPLETE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

            string phoneNumber = "phone_number";

            string phoneTypeVoip = "5";
  1. Instantiate a PhoneIdClient object containing your customer ID and API key. For Node.js, open a console log here.
console.log("## PhoneIDClient.phoneID ##");
        try {

            PhoneIdClient phoneIdClient = new PhoneIdClient(customerId, secretKey);
data = PhoneIdClient(customer_id, api_key)
phoneid_client = Telesign::PhoneIdClient.new(customer_id, api_key)
$data = new PhoneIdClient($customer_id, $api_key);
                    try
            {
                PhoneIdClient phoneIdClient = new PhoneIdClient(customerId, apiKey);
  1. Use Phone ID to check your phone number and store the results of your check in response/telesignResponse. For Node.js, declare a function that will check and store the response that comes from Phone ID.
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) {
            if (responseBody['phone_type']['code'] === phoneTypeVOIP) {
                console.log("Phone type in request is VoIP");
            } else {
                console.log("Phone type in request is not VoIP");
            }
        }
    } else {
        console.error("Unable to get PhoneID. " + error);
    }
}
            RestClient.TelesignResponse telesignResponse = phoneIdClient.phoneid(phoneNumber, null);

response = data.phoneid(phone_number)
response = phoneid_client.phoneid(phone_number)
$response = $data->phoneid($phone_number);
                RestClient.TelesignResponse telesignResponse = phoneIdClient.PhoneId(phoneNumber);
  1. Check phone_type. If it is "VOIP", print a message saying that the number is a VoIP phone. Otherwise, print a message saying it is not a VoIP phone.

For Node.js, this is where you create a PhoneID client. You pass in the function you defined in the last step.

client.phoneid.phoneID(messageCallback, phoneNumber);
            if (telesignResponse.ok) {
                if (telesignResponse.json.getAsJsonObject("phone_type").get("code").getAsString().equals(phoneTypeVoip)) {
                    System.out.println(String.format("Phone number %s is a VOIP phone.", phoneNumber));
                } else {
                    System.out.println(String.format("Phone number %s is not a VOIP phone.", phoneNumber));
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
if response.ok:
    if response.json['phone_type']['code'] == phone_type_voip:
        print("Phone number {} is a VoIP phone.".format(
            phone_number))
    else:
        print("Phone number {} is not a VoIP phone.".format(
            phone_number))
if response.ok
    if response.json['phone_type']['code'] == phone_type_voip
        puts "Phone number #{phone_number} is a VoIP phone."
    else
        puts "Phone number #{phone_number} is not a VoIP phone."
    end
end
if ($response->ok) {
  if ($response->json['phone_type']['code'] == $phone_type_voip) {
    echo "Phone number $phone_number is a VoIP phone.";
  }
  else {
    echo "Phone number $phone_number is not a VoIP phone.";
  }
}
                                if (telesignResponse.OK)
                {
                    if (telesignResponse.Json["phone_type"]["code"].ToString() == phoneTypeVoip)
                    {
                        Console.WriteLine(string.Format("Phone number {0} is a VoIP phone.", phoneNumber));
                    }
                    else
                    {
                        Console.WriteLine(string.Format("Phone number {0} is not a VoIP phone.", phoneNumber));
                    }
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e);
            }

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

📘

NOTE:

In a production integration, you would instead implement logic here to block the VoIP number.

  1. Run the code. It should submit the phone number you specified to a check by Phone ID. Depending on whether the phone type is VoIP or not, the appropriate message is displayed.

Sample code

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";
const timeout = 10*1000; // 10 secs

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

const phoneNumber = "Test phone number with no special characters or spaces goes here.";
const phoneTypeVOIP = "5";

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) {
            if (responseBody['phone_type']['code'] === phoneTypeVOIP) {
                console.log("Phone type in request is VoIP");
            } else {
                console.log("Phone type in request is not VoIP");
            }
        }
    } 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 CheckPhoneTypeToBlockVoip {

    public static void main(String[] args) {

        String customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
        String apiKey = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

        String phoneNumber = "Test phone number with no special characters or spaces goes here.";
        String phoneTypeVoip = "5";

        try {

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

            if (telesignResponse.ok) {
                if (telesignResponse.json.getAsJsonObject("phone_type").get("code").getAsString().equals(phoneTypeVoip)) {
                    System.out.println(String.format("Phone number %s is a VoIP phone.", phoneNumber));
                } else {
                    System.out.println(String.format("Phone number %s is not a VoIP phone.", phoneNumber));
                }
            }
        } 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----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="

phone_number = "Test phone number with no special characters or spaces goes here."
phone_type_voip = "5"

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

if response.ok:
    if response.json['phone_type']['code'] == phone_type_voip:
        print("Phone number {} is a VoIP phone.".format(
            phone_number))
    else:
        print("Phone number {} is not a VoIP phone.".format(
            phone_number))
require 'telesign'

customer_id = 'FFFFFFFF-EEEE-DDDD-1234-AB1234567890'
api_key = 'EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=='

phone_number = 'Test phone number with no special characters or spaces goes here.'
phone_type_voip = '5'

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

if response.ok
    if response.json['phone_type']['code'] == phone_type_voip
        puts "Phone number #{phone_number} is a VoIP phone."
    else
        puts "Phone number #{phone_number} is not a VoIP phone."
    end
end
<?php
require __DIR__ . "/../../vendor/autoload.php";
use telesign\sdk\phoneid\PhoneIdClient;
$customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
$api_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
$phone_number = "Test phone number with no special characters or spaces goes here.";
$phone_type_voip = "5";
$data = new PhoneIdClient($customer_id, $api_key);
$response = $data->phoneid($phone_number);
if ($response->ok) {
  if ($response->json['phone_type']['code'] == $phone_type_voip) {
    echo "Phone number $phone_number is a VoIP phone.";
  }
  else {
    echo "Phone number $phone_number is not a VoIP phone.";
  }
}
using System;

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

            string phoneNumber = "phone_number";

            string phoneTypeVoip = "5";

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

                if (telesignResponse.OK)
                {
                    if (telesignResponse.Json["phone_type"]["code"].ToString() == phoneTypeVoip)
                    {
                        Console.WriteLine(string.Format("Phone number {0} is a VoIP phone.", phoneNumber));
                    }
                    else
                    {
                        Console.WriteLine(string.Format("Phone number {0} is not a VoIP phone.", phoneNumber));
                    }
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e);
            }

            Console.WriteLine("Press any key to quit.");
            Console.ReadKey();
        }
    }
}
curl -X POST https://rest-api.telesign.com/v1/phoneid/<complete_phone_number> \
-d account_lifecycle_event="sign-in" \
-u "CUSTOMER_ID":"API_KEY"