Phone ID - Tutorial: Cleanse a number with Telesign Java 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 Java SDK to cleanse a phone number. Phone number cleansing corrects common formatting issues in submitted phone numbers. Skip to the end of this page to see the full sample code.

This code will take your test phone number, add an extra digit to make it invalid, and send it to Phone ID to cleanse. It then takes the cleansed phone number from the response and prints it to the console.

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 cleanse.
• 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

1. Follow the Telesign Self-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 as the project name.
   • Use phoneid 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.

2. 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/
   

Cleanse a number with Phone ID

1. Open the file "app/src/main/java/sendOTP/App.java".

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

3. Add the imports below between the package declaration. These imports reference selected functionality from the Telesign Self-service SDKs, as well as some other Java utilities.

   Java

   package phoneid;
   
   import com.telesign.PhoneIdClient;  
   import com.telesign.RestClient;
   

4. Add the App class declaration and 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.

5. 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==");
   

6. Define a variable in the main function to hold the phone number you want to cleanse. 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.

7. This code adds an extra digit to the number to make it invalid.

   Java

   String extraDigit = "0";
   String incorrectPhoneNumber = String.format("%s%s", phoneNumber, extraDigit);
   

8. Create a try-catch structure.

   Java

   try {
   
   } catch (Exception e) {
   
   }
   

9. In the try block, instantiate a PhoneIdClient object and pass it your customer ID and your API key.

   Java

   PhoneIdClient phoneIdClient = new PhoneIdClient(customerId, apiKey);
   

10. Next in the try block, use Phone ID to check and cleanse the incorrect phone number you created earlier.

RestClient.TelesignResponse telesignResponse = phoneIdClient.phoneid(incorrectPhoneNumber, null);

11. Next in the try block, use two print statements to check the results of the cleansing procedure on the incorrect phone number. The first print statement explains what the cleansed phone number is and displays the JSON response for the cleansed number. The second print statement shows the original phone number and displays the JSON response for the original phone number.

if (telesignResponse.ok) {
		System.out.println(String.format("Cleansed phone number has country code %s and phone number is %s.",
 			      telesignResponse.json.getAsJsonObject("numbering").getAsJsonObject("cleansing").getAsJsonObject("call").get("country_code").getAsString(),
 			      telesignResponse.json.getAsJsonObject("numbering").getAsJsonObject("cleansing").getAsJsonObject("call").get("phone_number").getAsString()));

	System.out.println(String.format("Original phone number was %s.",
 			      			    telesignResponse.json.getAsJsonObject("numbering").getAsJsonObject("original").get("complete_phone_number").getAsString()));
   }
} 

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

 e.printStackTrace();

13. If everything works, you send an incorrect phone number to Phone ID for cleansing, and you get back a response containing your cleansed phone number and the original phone number.

Test your integration

1. Switch from your editor to the terminal and run:

./gradlew build
./gradlew run

Sample code

package com.telesign.example.phoneid;

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

public class Cleansing {

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

        String extraDigit = "0";
        String incorrectPhoneNumber = String.format("%s%s", phoneNumber, extraDigit);

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

            if (telesignResponse.ok) {
                System.out.println(String.format("Cleansed phone number has country code %s and phone number is %s.",
                        telesignResponse.json.getAsJsonObject("numbering").getAsJsonObject("cleansing").getAsJsonObject("call").get("country_code").getAsString(),
                        telesignResponse.json.getAsJsonObject("numbering").getAsJsonObject("cleansing").getAsJsonObject("call").get("phone_number").getAsString()));

                System.out.println(String.format("Original phone number was %s.",
                        telesignResponse.json.getAsJsonObject("numbering").getAsJsonObject("original").get("complete_phone_number").getAsString()));
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}