Phone ID - Tutorial: Check phone type to block VoIP with Telesign Node.js SDK

📘

NOTE:

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

This tutorial walks you step-by-step through how to write code that makes a request to Telesign Phone ID using a Node.js SDK to identify voice over internet protocol (VoIP) numbers, so you can block them. Skip to the end of this page to see the full sample code.

📘

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 ready:

• Authentication credentials - Your Telesign Customer ID and API Key. If you don't have these already, see How do I find my Customer ID and API Key?
• Phone number - The phone number you want to get information about. 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.

📘

NOTE:

This tutorial uses the following:

• MacOS
• Node v16.9.0

Please modify accordingly if your developer environment differs from these details.

Set up your project

1. Follow the Telesign Self-service Node.js SDK install instructions here on GitHub incorporating these details:

   • Use phone_id as the project name.

2. Create a new file called phone_id_check_type.js and open it in your editor.

touch phone_id_check_type.js

You should end up in the top-level directory for your project in the Terminal.

Check phone type

1. Follow the steps below or copy the sample code into the file and update it accordingly.
2. Add the imports below. The telesignsdk import refers to the Telesign Self-service SDK.

const TelesignSDK = require('telesignsdk');

3. Define variables to store your authentication credentials. For testing purposes, you can just overwrite the default values below or use environment variables.

const customerId = process.env.CUSTOMER_ID || "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
const apiKey = process.env.API_KEY || "ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

4. Define a variable to hold the phone number you want to get information for and a variable to store the phone type, represented by a numerical identifier for a VoIP phone. The phone number should be a string with no spaces or special characters. Use the complete number, including the country code. For example: 16505551212.

const phoneNumber = process.env.PHONE_NUMBER || "11234567890";
const phoneTypeVOIP = "5";

5. Define rest_endpoint and timeout.

const rest_endpoint = "https://rest-api.telesign.com";
const timeout = 10*1000; // 10 secs

6. Instantiate a client object containing Customer ID, API key, REST endpoint, and timeout.

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

7. Set up 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'] === 300) {
            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);
    }
}

8. Create a PhoneID client using the function you created in the last step.

client.phoneid.phoneID(messageCallback, phoneNumber);

📘

NOTE:

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

6. If everything works, 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.

Test your integration

Switch from your editor to the terminal and run:

node phone_id_check_type.js

Sample code

const TeleSignSDK = require('telesignsdk');

const customerId = process.env.CUSTOMER_ID || "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
const apiKey = process.env.API_KEY || "ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

const phoneNumber = process.env.PHONE_NUMBER || "11234567890";
const phoneTypeVOIP = "5";

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

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'] === 300) {
            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);