Write to docs@telesign.com.
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();
}You must have the Contact Match add-on enabled for the code to work. Speak with your Customer Success 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 Customer Success Manager, or the links will not work):
- 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:
- 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”:{} |
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.