PhoneID API - Tutorial: Use 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();
}
from __future__ import print_function
from telesignenterprise.phoneid import PhoneIdClient
api_key = "Your API key goes here."
customer_id = "Your Customer ID goes here."
phone_number = "The phone number you want a match for goes here."
first_name = "The first name you are matching for."
last_name = "The last name you are matching for."
phoneid = PhoneIdClient(customer_id, api_key)
response = phoneid.phoneid(phone_number, addons={ "contact_match":{"first_name":first_name, "last_name":last_name}})
print(response.body)
require 'telesignenterprise'
CUSTOMER_ID = 'Your Customer ID goes here.'
API_KEY = 'Your API key goes here.'
phone_number = 'The phone number you want to match for goes here.'
first_name = 'Put the first name you are matching for here.'
last_name = 'Put the last name you are matching for here.'
phoneid_client = TelesignEnterprise::PhoneIdClient.new(CUSTOMER_ID, API_KEY)
response = phoneid_client.phoneid(phone_number, addons: {
contact_match: {
first_name: first_name,
last_name: last_name,
}
})
puts response.body
<?php
require __DIR__ . "/../../../php_telesign_enterprise/vendor/autoload.php";
use telesign\enterprise\sdk\phoneid\PhoneIdClient;
$CUSTOMER_ID = 'Your Customer ID goes here.';
$API_KEY = 'Your API key goes here.';
$phone_number = 'The phone number you want to match for goes here.';
$first_name = 'Put the first name you are matching for here.';
$last_name = 'Put the last name you are matching for here.';
$client = new PhoneIdClient($CUSTOMER_ID, $API_KEY);
$response = $client->phoneid($phone_number,
[
"addons" => [
"contact_match" => [
"first_name" => $first_name,
"last_name" => $last_name]
]
]
);
print_r($response->json);
const TelesignSDK = require('telesignsdk');
const customerId = 'Your Customer ID goes here.';
const api_key = 'Your API key goes here.';
const phoneNumber = 'The phone number you want to match for goes here.';
const firstName = 'The first name you want to match for goes here.';
const lastName = 'The last name you want to match for goes here.';
const client = new TelesignSDK(customerId, api_key);
function callback (error, data) {
if (error === null) {
console.log(`PhoneID response for phone number: ${phoneNumber} ` +
`=> code: ${data['status']['code']}, ` +
`description: ${data['status']['description']}`);
if (data['contact_match']['status']['code'] === 2800) {
console.log(
`Contact match scored first name ${data['contact_match']['first_name_score']} and scored` +
`last name ${data['contact_match']['last_name_score']}.`);
} else {
console.log(`Contact match did not run successfully: ${data['contact_match']['status']['description']}`)
}
} else {
console.error(`Unable to get PhoneID. ${error}`);
}
}
client.phoneid.phoneID(callback, phoneNumber, {
addons: {
contact_match: {
first_name: firstName,
last_name: lastName
}
}
});
NOTE:
You must have the Contact Match add-on enabled for the code to work. Speak with our Customer Support Team 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 - Download the SDK from TeleSign’s GitHub repository for your selected language:
- 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')
<dependency>
<groupId>com.telesign</groupId>
<artifactId>telesign</artifactId>
<version>[current_version]</version>
</dependency>
python Python
From a terminal run:
pip install telesign
```shell Ruby
# From a terminal run:
gem install telesign
```shell PHP
# From a terminal run:
composer require telesign/telesign
```shell C#
$ nuget pack .\Path\To\csharp_telesign_enterprise\TelesignEnterprise\TelesignEnterprise.csproj
$ Install-Package .\Path\To\TelesignEnterprise-(insert latest version).nupkg
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;
from __future__ import print_function
from telesignenterprise.phoneid import PhoneIdClient
require 'telesignenterprise'
<?php
require __DIR__ . "/../../../php_telesign_enterprise/vendor/autoload.php";
use telesign\enterprise\sdk\phoneid\PhoneIdClient;
const TelesignSDK = require('telesignsdk');
- 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.";
api_key = "Your API key goes here."
customer_id = "Your Customer ID goes here."
phone_number = "The phone number you want a match for goes here."
first_name = "The first name you are matching for."
last_name = "The last name you are matching for."
CUSTOMER_ID = 'Your Customer ID goes here.'
API_KEY = 'Your API key goes here.'
phone_number = 'The phone number you want to match for goes here.'
first_name = 'Put the first name you are matching for here.'
last_name = 'Put the last name you are matching for here.'
$CUSTOMER_ID = 'Your Customer ID goes here.';
$API_KEY = 'Your API key goes here.';
$phone_number = 'The phone number you want to match for goes here.';
$first_name = 'Put the first name you are matching for here.';
$last_name = 'Put the last name you are matching for here.';
const customerId = 'Your Customer ID goes here.';
const api_key = 'Your API key goes here.';
const phoneNumber = 'The phone number you want to match for goes here.';
const firstName = 'The first name you want to match for goes here.';
const lastName = 'The last name you want to match for goes 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();
}
phoneid = PhoneIdClient(customer_id, api_key)
response = phoneid.phoneid(phone_number, addons={ "contact_match":{"first_name":first_name, "last_name":last_name}})
print(response.body)
phoneid_client = TelesignEnterprise::PhoneIdClient.new(CUSTOMER_ID, API_KEY)
response = phoneid_client.phoneid(phone_number, addons: {
contact_match: {
first_name: first_name,
last_name: last_name,
}
})
puts response.body
$client = new PhoneIdClient($CUSTOMER_ID, $API_KEY);
$response = $client->phoneid($phone_number,
[
"addons" => [
"contact_match" => [
"first_name" => $first_name,
"last_name" => $last_name]
]
]
);
print_r($response->json);
function callback (error, data) {
if (error === null) {
console.log(`PhoneID response for phone number: ${phoneNumber} ` +
`=> code: ${data['status']['code']}, ` +
`description: ${data['status']['description']}`);
if (data['contact_match']['status']['code'] === 2800) {
console.log(
`Contact match scored first name ${data['contact_match']['first_name_score']} and scored` +
`last name ${data['contact_match']['last_name_score']}.`);
} else {
console.log(`Contact match did not run successfully: ${data['contact_match']['status']['description']}`)
}
} else {
console.error(`Unable to get PhoneID. ${error}`);
}
}
client.phoneid.phoneID(callback, phoneNumber, {
addons: {
contact_match: {
first_name: firstName,
last_name: lastName
}
}
});
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.
Updated 8 months ago