Phone ID - Tutorial: Use Contact Match with Telesign Java SDK

📘

NOTE:

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

This tutorial describes how to use the Phone ID Contact Match identity attribute with the Telesign Java SDK, guiding you step-by-step through the creation of an integration that uses the Phone ID Contact Match. Skip to the end of this page to see the full sample code.

Before you begin

Make sure you have the following before you start:

• Authentication credentials: Your Customer ID and API Key. If you need help finding these items, go to the support article 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.
• Phone number - The phone number you want to get information about.
• 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. 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 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 and .java source files from the Telesign Full-service SDK copied into it.

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/
   

Make a Contact Match 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;
   
   import com.telesign.PhoneIdClient;
   import com.telesign.RestClient;
   import com.telesign.Util;
   
   import java.util.HashMap;
   

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 get information for. 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 variables in the main function to hold the first name and last name that you want to match.

   Java

   String firstName = "John";
   String lastName = "Doe";
   

7. Add code to instantiate a PhoneIdClient object containing your Customer ID and API Key.

   Java

   PhoneIdClient phoneIdClient = new PhoneIdClient(customerId, apiKey);
   

8. Create a new hash map, and use it to store the params you are going to send to Telesign Phone ID. This allows you to store the object and then pass the identity attribute, contact_match, that you want to use.

   Java

   HashMap<String, Object> params = new HashMap<String, Object>() {{
            put("addons",
                    new HashMap<String, Object>() {{
                        put("contact_match", new HashMap<String, String>() {{
                            put("first_name", firstName);
                            put("last_name", lastName);
                        }});
                    }});
        }};
   

9. Create a try-catch structure.

   Java

    try {
   
   } catch (Exception e) {
       
   }
   

10. In the try block, make the request and capture the response.

    Java

    RestClient.TelesignResponse response = phoneIdClient.phoneid(phoneNumber, params);
    

11. Next in the try block, display the response for debugging purposes. In your production code, you would likely remove this.

    Java

    System.out.println(response.body);
    

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.

    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
   

   
   

Sample code

package phoneid;

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

import java.util.HashMap;

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"); //The phone number you want to match for goes here.
        String firstName = "Put the first name you are matching for here.";
        String lastName = "Put the last name you are matching for here.";
        
        PhoneIdClient phoneIdClient = new PhoneIdClient(customerId, apiKey);
      
        HashMap<String, Object> params = new HashMap<String, Object>() {{
            put("addons",
                    new HashMap<String, Object>() {{
                        put("contact_match", new HashMap<String, String>() {{
                            put("first_name", firstName);
                            put("last_name", lastName);
                        }});
                    }});
        }};
        try {
            RestClient.TelesignResponse response = phoneIdClient.phoneid(phoneNumber, params);
            System.out.println(response.body);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}