Phone ID - Tutorial: Use identity attributes with an SDK

This tutorial describes how to use the Phone ID Contact Match identity attribute using a Telesign SDK.

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

An identity attribute provides additional information about a phone number with one call to Phone ID. This is in addition to the standard response fields for Phone ID. You get back status information for each identity attribute enabled and requested.

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 a Telesign expert.
Phone number - The phone number you want to get information about. If you are a self-service customer and have not added money to your account yet, you need to first get the phone number verified by Telesign by adding it to your list of Test Numbers.

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

Copy the sample code below into a local file.
Add 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 these variables:

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 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.
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 add-ons you want to use.

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

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

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

📘NOTE:

Before you begin

Install the SDK

Make Contact Match request

Sample code

📘
NOTE: