Phone ID - Tutorial: Perform a number deactivation check with Telesign Node.js SDK

📘

NOTE:

To add Number Deactivation to your account, contact a Telesign expert. This feature is available for full-service accounts only.

This tutorial explains how to check whether a phone number was deactivated using the Phone ID Number Deactivation identity attribute with the Telesign Node.js SDK. You can use the check to decide whether to send someone an SMS or Voice message. If someone's number is not active, you can save the cost of attempting to send a message. Skip to the end of this page to see the full sample code.

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?
• Identity attribute enabled - Make sure the Number Deactivation identity attribute is enabled by Telesign. If it is not yet enabled, contact a Telesign expert.

📘

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 Full-service Node.js SDK install instructions here on GitHub incorporating these details:

   • Use phoneidTest as the project name.

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

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

   Terminal

   touch phone_id_deactivation_check.js
   

Make Number Deactivation request

1. Follow the steps below or copy the sample code into a file and update accordingly.

2. Import this dependency from the SDK.

   JavaScript

   var TeleSignSDK = require('telesignenterprisesdk');
   

3. Define variables to store your authentication credentials.

   JavaScript

   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 perform a number deactivation check on. This should be a string with no spaces or special characters. Use the complete number, including the country code. For example: 16505551212.

   JavaScript

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

   📘

   NOTE:

   In your production integration, pull the phone number from your recipient database instead of hardcoding it.

5. Define a variable to hold the ucid which is the use case code that provides information about what kind of transaction you are performing.

   JavaScript

   const ucid = "ATCK";
   

6. Instantiate a client object containing your Customer ID and API Key.

   JavaScript

   const client = new TeleSignSDK(customerId, apiKey);
   

7. Define a callback function to create a function to handle the callback after you send a request for a number deactivation check.

   JavaScript

   function phoneidCallback(error, responseBody) {
       if (error === null) {
   
           if (responseBody.hasOwnProperty('number_deactivation')) {
               console.log(`PhoneID response for phone number: ${phoneNumber}` +
                   ` => phone number: ${responseBody['number_deactivation']['number']}` +
                   `, last deactivated: ${responseBody['number_deactivation']['last_deactivated']}`);
           } else {
               console.log(`Phone number ${phoneNumber} has not been deactivated.`);
               console.log(responseBody);
           }
   
       } else {
           console.error("Unable to send phoneID numberDeactivation. " + error);
       }
   }
   

8. Send the request and pass in the phoneidCallbackfunction you created to handle the response.

   JavaScript

   client.phoneid.numberDeactivation(phoneidCallback, phoneNumber, ucid);
   

Test your integration

1. Switch from your editor to the terminal and build your project. Make sure you are in the top-level directory of your project.

   Terminal

   node phone_id_contact_match.js
   

You should receive a response containing details about whether your phone number is active or not. You can use these results to make decisions about what to do with the phone number. For example, if someone is trying to sign up for an account with an inactive number, you might require them to sign up using a different number. Or, if you needed to send the provided number a code via text or voice message, you might opt not to send the message since it will not reach a deactivated number.

Sample code

var TeleSignSDK = require('telesignenterprisesdk');


console.log("## phoneid.numberDeactivation ##");

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 ucid = "ATCK";

const client = new TeleSignSDK(customerId, apiKey);

function phoneidCallback(error, responseBody) {
    if (error === null) {

        if (responseBody.hasOwnProperty('number_deactivation')) {
            console.log(`PhoneID response for phone number: ${phoneNumber}` +
                ` => phone number: ${responseBody['number_deactivation']['number']}` +
                `, last deactivated: ${responseBody['number_deactivation']['last_deactivated']}`);
        } else {
            console.log(`Phone number ${phoneNumber} has not been deactivated.`);
            console.log(responseBody);
        }

    } else {
        console.error("Unable to send phoneID numberDeactivation. " + error);
    }
}

client.phoneid.numberDeactivation(phoneidCallback, phoneNumber, ucid);