PhoneID Contact Match Add-on with an SDK

package com.telesign.example.phoneid;

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

private static void contact_match() {
        PhoneIdClient phoneIdClient = new PhoneIdClient(customerId, apiKey);
        String phoneNumber = "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.";
        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.json);

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

NOTE:

You must have the Contact Match add-on enabled for the code to work. Speak with your Technical Account Manager to enable the add-ons you want.

This tutorial describes how to implement the PhoneID Contact Match add-on using a TeleSign SDK. An add-on lets you easily request additional information about a phone number using the PhoneID API without doing a lot of extra implementation work. When you include an add-on in your request to the PhoneID API, you get back all of the information normally provided by the PhoneID API, and then whatever information is specific to the add-on.

You get back status information for each part of your request. For example, if you send a request to the PhoneID API, and you include a request for information from the Contact add-on and the Number Deactivation add-on, you would get back PhoneID information and status information about the PhoneID part of your request, Contact information and status information about the Contact add-on part of your request, and Number Deactivation information and status information about the Number Deactivation part of your request.

Available add-ons you may want to implement (with the JSON for how you would send your request for each) include:

Contact Add-on - allows you to retrieve the name and address associated with the phone number you submit, without requesting explicit consent from your end user. "contact":{}
Contact Plus Add-on - requires explicit consent from your end users, and once obtained, allows TeleSign to directly access a subscriber’s name and address on file with the carrier. "contact_plus":{"billing_postal_code":90028}
Contact Match Add-on - allows you to compare a name and address for a submitted phone number in your request with a name and address on file with the carrier and return a score referred to as a match score that tells you how close a match was found. "contact_match":{"first_name": "User First Name", "last_name":"User Last Name", "address": "123 Main St", "city": "Marina Del Rey", "postal_code":"95120", "state":"CA", "country":"USA"}
Device Info Add-on - allows you to receive phone manufacturer and model information about a device associated with the phone number you submit. “device_info”: {}
Number Deactivation Add-on - allows you to find out whether a phone number has been deactivated, when it was deactivated, and by which carrier the phone number was deactivated based on carriers’ phone number data and TeleSign’s proprietary analysis. "number_deactivation":{}
Subscriber Status Add-on - allows you to find out the current carrier subscriber status (prepaid or postpaid; active, suspended, deactivated; account type; primary account holder; length of account tenure). "subscriber_status":{}
Porting History Add-on - allows you to find out at what point and where a phone number was ported to. "porting_history":{}

Requirements

For this tutorial, the following is required:

customer ID - obtain from your account by logging in to teleportal.telesign.com
API key - obtain from your account by logging in to teleportal.telesign.com
SDK - Access to TeleSign’s GitHub repository for your selected language (you must request access from your Technical Account Manager, or the links will not work):
- Java
- Python
- Ruby
- PHP
- C#
Language Version
- Java - 7+
- Python - 2.7+
- Ruby - 2+
- PHP - 5.6+
- C# - 4.5+

Install the SDK

Obtain your customer ID and API key.
Log in to GitHub and choose the SDK in your preferred language:
- Java: Browse / Download
- Python: Browse / Download
- Ruby: Browse / Download
- PHP: Browse / Download
- C#: Browse / Download
Download or clone the repository. If you download it, extract the repository from the .ZIP file.
To install the SDK for use, do the following:

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

Use Contact Match PhoneID Add-on

This section walks you through the code. For the example, only first and last name are used. You can add more options you want to match for.

Begin by adding statements for including the appropriate part of the TeleSign SDK and any additional language specific functions you may need.

package com.telesign.example.phoneid;

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

Insert values for each of the items listed.
- customer_id (customerId for Java/C#) - Your TeleSign assigned customer ID, available in your account information in the portal.
- api_key (apiKey for Java/C#) - Your TeleSign assigned API key, available in your account information in the portal.
- phone_number (phoneNumber for Java/C#) - The phone number you want to use for the example. If you are doing a free trial, the phone number must be verified (verifying the number is not required if you are a paying customer). When you provide the number, it should be a string with no spaces or special characters. Include the complete number. For example, if you are doing a phone number for America, you would include the country code and the area code with the number. For example 16505551212.
- first_name (firstName for Java/C#) - The first name you want a match for.
- last_name (lastName for Java/C#) - The last name you want a match for.

private static void contact_match() {
        PhoneIdClient phoneIdClient = new PhoneIdClient(customerId, apiKey);
        String phoneNumber = "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.";

Instantiate a PhoneIdClient object countaining your customer ID and API key. Store the object, and pass it your phone number and the add-ons you want to use. In this walkthrough, you are using the Contact Match add-on. You must have the add-ons you want to enabled prior to using them, or they will not work. Add-on choices are presented here with the json you need to put in for the addons parameter:

Add-on	Code
Contact	“contact”:{}
Contact Plus	“contact_plus”:{“billing_postal_code”:zip_code}
Contact Match	“contact_match”:{“first_name”: “User First Name”, “last_name”:“User Last Name”, “address”: “123 Main St”, “city”: “Marina Del Rey”, “postal_code”:“95120”, “state”:“CA”, “country”:“USA”}
Device Info	“device_info”:{}
Number Deactivation	“number_deactivation”:{}
Subscriber Status	“subscriber_status”:{}
Porting History	“porting_history”:{}

NOTE:

If you are using Contact Match for a number in China, you must use chinese unicode characters for first and last name. First and last name are the only fields you can do a match for.

/* You instantiated a PhoneIDClient object in the last step for 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);
                        }});
                    }});
        }};
        try {
            RestClient.TelesignResponse response = phoneIdClient.phoneid(phoneNumber, params);
            System.out.println(response.json);

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

Code it Without the SDK

You can see an example of how to use add-ons without an SDK by checking out the Use PhoneID Add-ons tutorial. A Python code sample showing you how to use add-ons with basic authentication is shown.

You can learn more about add-ons by going to the PhoneID API page, or looking at one of that page’s add-on subpages.

You can read more about authentication on the Authentication page.