Phone ID - Tutorial: Perform a number deactivation check

This tutorial explains how to check whether a phone number was deactivated using the Phone ID Number Deactivation identity attribute. 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.

📘

NOTE:

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

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 Contact Match identity attribute is enabled by Telesign. If it is not yet enabled, contact a Telesign expert.

Install the SDK

1. Sign in to GitHub and choose the SDK in your preferred language.
2. Download a ZIP file of the SDK or clone the repository.
3. If you downloaded, extract the repository from the .ZIP file.
4. Install the SDK using the following:

Node.js

npm install telesignsdk -save

Java (Gradle)

compile files('path/to/jar/telesignenterprise-(insert latest version).jar')

Java (Maven)

<dependency>
    <groupId>com.telesign</groupId>
    <artifactId>telesign</artifactId>
    <version>(insert latest version)</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/path/to/jar/telesignenterprise-(insert latest version).jar</systemPath>
</dependency>

Python

# From a terminal run:
pip install -e ~/path/to/python_telesign_enterprise

Ruby

# From a terminal run:
gem install telesign

PHP

# From a terminal run:
composer require telesign/telesign

C#

# Build and install the TeleSignEnterprise package:
nuget pack .\Path\To\csharp_telesign_enterprise\TelesignEnterprise\TelesignEnterprise.csproj
Install-Package .\Path\To\TelesignEnterprise-(insert latest version).nupkg

Make Number Deactivation request

This section walks you through the sample code below:

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

Node

var TeleSignSDK = require('telesignenterprisesdk');

Java

package com.telesign.enterprise.example.phoneid_number_deactivation;

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

Python

from __future__ import print_function
from telesignenterprise.phoneid import PhoneIdClient

Ruby

require 'telesignenterprise'

PHP

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

C#

using Newtonsoft.Json.Linq;
using System;
using Telesign;

2. Insert values for each of these variables:

• customer_id / customerId - Your Telesign assigned Customer ID.
• api_key / apiKey - Your Telesign assigned API Key.
• phone_number / phoneNumber - The phone number you want to request information for. This should be a string with no spaces or special characters. Use the complete number, including the country code. For example:16505551212.
• ucid - A string that specifies one of the use case codes. Use case codes provide information about what kind of transaction you are performing.

Node

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

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

Java

public class CheckPhoneNumberDeactivated {

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

Python

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

Ruby

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.'
ucid = 'ATCK'

PHP

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

C#

namespace TelesignEnterprise.Example.PhoneNumberDeactivation
{
    public class CheckPhoneNumberDeactivated
    {
        public 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 ucid = "ATCK";

3. Instantiate a PhoneIdClient object and pass it your Customer ID and API Key. For Node.js, it is just client.

Node

const client = new TeleSignSDK(customerId, apiKey);

Java

        try {

            PhoneIdClient phoneIdClient = new PhoneIdClient(customerId, apiKey);

Python

phoneid = PhoneIdClient(customer_id, api_key)

Ruby

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

PHP

$phoneid = new PhoneIdClient($customer_id, $api_key);

C#

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

4. Perform a number deactivation check, and store the results in the variable response/telesignResponse. For Node.js, you use this step to create a function to handle the callback after you send a request for a number deactivation check.

Node

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

        if (responseBody.hasOwnProperty('number_deactivation') || responseBody['status'][]) {
            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);
    }
}

Java

            RestClient.TelesignResponse telesignResponse = phoneIdClient.numberDeactivation(phoneNumber, ucid, null);

Python

response = phoneid.number_deactivation(phone_number, ucid)

Ruby

response = phoneid_client.number_deactivation(phone_number, ucid)

PHP

$response = $phoneid->numberDeactivation($phone_number, $ucid);

C#

                RestClient.TelesignResponse telesignResponse = phoneIdClient.NumberDeactivation(phoneNumber, ucid);

5. The results stored in the response/telesignResponse variable are provided to you in this step. For node.js, this is where you send the request. You pass in the phoneidCallback function you created to handle the response.

Node

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

Java

             if (telesignResponse.ok) {
                if (!telesignResponse.json.getAsJsonObject("number_deactivation").get("last_deactivated").isJsonNull()) {
                    System.out.println(String.format("Phone number %s was last deactivated %s.",
                            telesignResponse.json.getAsJsonObject("number_deactivation").get("number").getAsString(),
                            telesignResponse.json.getAsJsonObject("number_deactivation").get("last_deactivated").getAsString()));
                } else {
                    System.out.println(String.format("Phone number %s has not been deactivated.",
                            telesignResponse.json.getAsJsonObject("number_deactivation").get("number").getAsString()));
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Python

if response.ok:
    if response.json['number_deactivation']['last_deactivated']:
        print("Phone number {} was last deactivated {}.".format(
            response.json['number_deactivation']['number'],
            response.json['number_deactivation']['last_deactivated']))
    else:
        print("Phone number {} has not been deactivated.".format(response.json['number_deactivation']['number']))

Ruby

if response.ok
  if response.json['number_deactivation']['last_deactivated']
    puts 'Phone number %s was last deactivated %s.' %
             [response.json['number_deactivation']['number'],
              response.json['number_deactivation']['last_deactivated']]
  else
    puts 'Phone number %s has not been deactivated.' %
             response.json['number_deactivation']['number']
  end
end

PHP

if ($response->ok) {
  if ($response->json['number_deactivation']['last_deactivated']) {
    echo "Phone number {$response->json["number_deactivation"]["number"]}"
    . " was last deactivated {$response->json["number_deactivation"]["last_deactivated"]}.";
  }
  else {
    echo "Phone number {$response->json['number_deactivation']['number']} has not been deactivated.";
  }
}

C#

                if (telesignResponse.OK)
                {
                    if (telesignResponse.Json["number_deactivation"]["last_deactivated"].Type != JTokenType.Null)
                    {
                        Console.WriteLine(string.Format("Phone number {0} was last deactivated {1}.",
                                telesignResponse.Json["number_deactivation"]["number"],
                                telesignResponse.Json["number_deactivation"]["last_deactivated"]));
                    }
                    else
                    {
                        Console.WriteLine(string.Format("Phone number {0} has not been deactivated.",
                                telesignResponse.Json["number_deactivation"]["number"]));
                    }
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e);
            }

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

6. 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

Node

var TeleSignSDK = require('telesignenterprisesdk');


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

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

const client = new TeleSignSDK(customerId, apiKey);

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

        if (responseBody.hasOwnProperty('number_deactivation') || responseBody['status'][]) {
            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);

Java

package com.telesign.enterprise.example.phoneid_number_deactivation;

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

public class CheckPhoneNumberDeactivated {

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

        try {

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

            if (telesignResponse.ok) {
                if (!telesignResponse.json.getAsJsonObject("number_deactivation").get("last_deactivated").isJsonNull()) {
                    System.out.println(String.format("Phone number %s was last deactivated %s.",
                            telesignResponse.json.getAsJsonObject("number_deactivation").get("number").getAsString(),
                            telesignResponse.json.getAsJsonObject("number_deactivation").get("last_deactivated").getAsString()));
                } else {
                    System.out.println(String.format("Phone number %s has not been deactivated.",
                            telesignResponse.json.getAsJsonObject("number_deactivation").get("number").getAsString()));
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Python

from __future__ import print_function
from telesignenterprise.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."
ucid = "ATCK"

phoneid = PhoneIdClient(customer_id, api_key)
response = phoneid.number_deactivation(phone_number, ucid)

if response.ok:
    if response.json['number_deactivation']['last_deactivated']:
        print("Phone number {} was last deactivated {}.".format(
            response.json['number_deactivation']['number'],
            response.json['number_deactivation']['last_deactivated']))
    else:
        print("Phone number {} has not been deactivated.".format(response.json['number_deactivation']['number']))

Ruby

require 'telesignenterprise'

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.'
ucid = 'ATCK'

phoneid_client = TelesignEnterprise::PhoneIdClient.new(customer_id, api_key)
response = phoneid_client.number_deactivation(phone_number, ucid)

if response.ok
  if response.json['number_deactivation']['last_deactivated']
    puts 'Phone number %s was last deactivated %s.' %
             [response.json['number_deactivation']['number'],
              response.json['number_deactivation']['last_deactivated']]
  else
    puts 'Phone number %s has not been deactivated.' %
             response.json['number_deactivation']['number']
  end
end

PHP

<?php
require __DIR__ . "/../../vendor/autoload.php";
use telesign\enterprise\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.";
$ucid = "ATCK";
$phoneid = new PhoneIdClient($customer_id, $api_key);
$response = $phoneid->numberDeactivation($phone_number, $ucid);
if ($response->ok) {
  if ($response->json['number_deactivation']['last_deactivated']) {
    echo "Phone number {$response->json["number_deactivation"]["number"]}"
    . " was last deactivated {$response->json["number_deactivation"]["last_deactivated"]}.";
  }
  else {
    echo "Phone number {$response->json['number_deactivation']['number']} has not been deactivated.";
  }
}

C#

using Newtonsoft.Json.Linq;
using System;
using Telesign;

namespace TelesignEnterprise.Example.PhoneNumberDeactivation
{
    public class CheckPhoneNumberDeactivated
    {
        public 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 ucid = "ATCK";

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

                if (telesignResponse.OK)
                {
                    if (telesignResponse.Json["number_deactivation"]["last_deactivated"].Type != JTokenType.Null)
                    {
                        Console.WriteLine(string.Format("Phone number {0} was last deactivated {1}.",
                                telesignResponse.Json["number_deactivation"]["number"],
                                telesignResponse.Json["number_deactivation"]["last_deactivated"]));
                    }
                    else
                    {
                        Console.WriteLine(string.Format("Phone number {0} has not been deactivated.",
                                telesignResponse.Json["number_deactivation"]["number"]));
                    }
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e);
            }

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

cURL

curl -X GET https://rest-ww.telesign.com/v1/phoneid/number_deactivation/15555551212 -u "CUSTOMER ID":"API KEY"