Phone ID - Tutorial: Use Contact Match with an SDK

This tutorial describes how to implement the Phone ID Contact Match identity attribute using a Telesign SDK. An identity attribute lets you request additional information about a phone number along with the standard results of a Phone ID request.

📘
NOTE:
To add Contact Match to your account, contact a Telesign expert.

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?
Identity attribute enabled - Make sure the Contact Match identity attribute is enabled by Telesign. If it is not yet enabled, contact our Customer Support Team.

Install the SDK

Sign in to GitHub and choose the SDK in your preferred language.
Download a ZIP file of the SDK or clone the repository.
If you downloaded, extract the repository from the .ZIP file.
Install the SDK using 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>

# From a terminal run:
pip install telesign

# From a terminal run:
gem install telesign

# From a terminal run:
composer require telesign/telesign

nuget pack .\Path\To\csharp_telesign_enterprise\TelesignEnterprise\TelesignEnterprise.csproj
Install-Package .\Path\To\TelesignEnterprise-(insert latest version).nupkg

Make Contact Match request

This section walks you through the sample code below:

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 variables below:

customer_id (customerId for Java/C#) - Your Telesign-assigned Customer ID.
api_key (apiKey for Java/C#) - Your Telesign-assigned API Key.
phone_number (phoneNumber for Java/C#) - The phone number you want to request information for. This should be a string with no spaces or special characters. Use the complete number, including the country code. 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 containing your Customer ID and API Key. Store the object, and pass it your phone number and an input object for the Contact Match identity attribute.

Sample Code

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 identity attribute enabled for the code to work. Speak with our Customer Support Team to enable the identity attribute you want.

This tutorial describes how to implement the PhoneID Contact Match identity attribute using a Telesign SDK. An identity attribute lets you easily request additional information about a phone number using Phone ID without doing a lot of extra implementation work. When you include an identity attribute in your request, you get additional information in the HTTP response.

Requirements

For this tutorial, the following is required:

Customer ID - obtain from your account by signing in to teleportal.telesign.com
API key - obtain from your account by signing in to teleportal.telesign.com
SDK - Download the SDK from TeleSign’s GitHub repository for your selected language:
- 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.
Sign 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')

<dependency>
    <groupId>com.telesign</groupId>
    <artifactId>telesign</artifactId>
    <version>[current_version]</version>
</dependency>

# From a terminal run:
pip install telesign

# From a terminal run:
gem install telesign

# From a terminal run:
composer require telesign/telesign

nuget pack .\Path\To\csharp_telesign_enterprise\TelesignEnterprise\TelesignEnterprise.csproj
Install-Package .\Path\To\TelesignEnterprise-(insert latest version).nupkg

Use Contact Match

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 containing your Customer ID and API key. Store the object, and pass it your phone number and the request parameters for Contact Match.

Example Contact Match request parameters:

"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"}

/* 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
        }
    }
});

Phone ID - Tutorial: Use Contact Match with an SDK

📘
NOTE:

Before you begin

Install the SDK

Make Contact Match request

Sample Code

📘
NOTE:

Requirements

Install the SDK

Use Contact Match

📘NOTE:

Before you begin

Install the SDK

Make Contact Match request

Sample Code

📘NOTE:

Requirements

Install the SDK

Use Contact Match

📘
NOTE:

📘
NOTE: