Phone ID - Tutorial: Perform a number deactivation check with Telesign Java 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 Java 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.
• Gradle: This package manager isn't required to use the SDK, but it is required for this tutorial.

📘

NOTE:

This tutorial uses the following:

• MacOS
• Java OpenJDK v19.0.1
• Gradle 7.6

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

Set up your project

📘

NOTE:

The installation process for the Telesign Full-service Java SDK will also install the Telesign Self-service Java SDK since it is a dependency for the Full-service SDK.

1. Open the file app/src/main/java/phoneid_number_deactivation/App.java.

2. Follow the Telesign Full-service Java SDK install instructions here on GitHub incorporating these details:

   • Use phoneidTest as the project directory name.
   • Use JUnit 4 as the test framework.
   • Use phoneid_number_deactivation as the project name.
   • Use phoneid_number_deactivation as the source package name.

   You should end up in the top-level directory ("phoneidTest") for your project in the Terminal. This directory should contain an initialized Gradle project with the Telesign Self-service SDK included in its dependencies and .java source files from the Telesign Full-service SDK copied into it.

3. From the top level of your project, delete the folder "app/src/test/". No tests are included in this tutorial.

   Terminal

   rm -r app/src/test/
   

Make Number Deactivation request

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

2. Add these imports between the package declaration and the App class declaration. These imports reference selected functionality from the Telesign Self-service and Full-service SDKs, as well as some other Java utilities.

   Java

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

3. Replace the default App class with the following basic structure.

   Java

      public class App {
          public static void main(String[] args) {
          
          }
      }
   

   In the next step, you will begin adding statements to the main function in the App class.

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

   Java

   String customerId = System.getenv().getOrDefault("CUSTOMER_ID", "FFFFFFFF-EEEE-DDDD-1234-AB1234567890");
   String apiKey = System.getenv().getOrDefault("API_KEY", "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==");
   

5. Define a variable in the main function 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.

   Java

   String phoneNumber = System.getenv().getOrDefault("PHONE_NUMBER", "123456789"); 
   

   📘

   NOTE:

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

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

   Java

   String ucid = "ATCK";
   

7. Create a try-catch structure.

   Java

    try {
   
   } catch (Exception e) {
       
   }
   

8. Add code to instantiate a PhoneIdClient object containing your Customer ID and API Key to the try block.

   Java

   PhoneIdClient phoneIdClient = new PhoneIdClient(customerId, apiKey);
   

9. In the try block, perform a number deactivation check, and store the results in the variable telesignResponse.

   Java

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

10. The results stored in the telesignResponse variable are provided to you in this step as shown in the try block in the sample code.

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

    📘

    NOTE:

    Use System.out.printlnto display the response for debugging purposes. In your production code, you would likely remove this from your code.

11. In the catch block, add code to display any type of exception and associated error code that might occur. Again, this is for debugging purposes. In your production code, you would likely remove this.

    Java

    e.printStackTrace();
    

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

   ./gradlew build
   

2. Run your project.

   Terminal

   ./gradlew run
   

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

package phoneid_number_deactivation;

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

public class App {

    public static void main(String[] args) {

        String customerId = System.getenv().getOrDefault("CUSTOMER_ID", "FFFFFFFF-EEEE-DDDD-1234-AB1234567890");
        String apiKey = System.getenv().getOrDefault("API_KEY", "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==");

        String phoneNumber = System.getenv().getOrDefault("PHONE_NUMBER", "123456789");// 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();
        }
    }
}