Tutorial: Phone Number Risk Level with Score

var TeleSignSDK = require('telesignsdk');

const customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"; // Todo: find in portal.telesign.com
const apiKey = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="; // Todo: find in portal.telesign.com
const rest_endpoint = "https://rest-api.telesign.com"; 
const timeout = 10*1000; // 10 secs

const client = new TeleSignSDK( customerId,
    apiKey,
    rest_endpoint,
    timeout // optional
    // userAgent
);

const phoneNumber = "Your test phone number with no special characters or spaces.";
const accountLifeCycleEvent = "create";

console.log("## ScoreClient.score ##");

function score_callback(error, response_body) {
    if (error === null) {
        console.log(`Score response for phone number: ${phoneNumber}` +
            ` => code: ${response_body['status']['code']}` +
            `, description: ${response_body['status']['description']}`);
    } else {
        console.error("Unable to get score. " + error);
    }
}

client.score.score(score_callback, phoneNumber, accountLifeCycleEvent);
package com.telesign.example.score;

import com.telesign.RestClient;
import com.telesign.ScoreClient;

public class CheckPhoneNumberRiskLevel {

    public static void main(String[] args) {

        String customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
        String apiKey = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

        String phoneNumber = "Your test phone number with no special characters or spaces.";
        String accountLifecycleEvent = "create";

        try {
            ScoreClient scoreClient = new ScoreClient(customerId, apiKey);
            RestClient.TelesignResponse telesignResponse = scoreClient.score(phoneNumber, accountLifecycleEvent, null);

            if (telesignResponse.ok) {
                System.out.println(String.format("Phone number %s has a '%s' risk level and the recommendation is to '%s' the transaction.",
                        phoneNumber,
                        telesignResponse.json.getAsJsonObject("risk").get("level").getAsString(),
                        telesignResponse.json.getAsJsonObject("risk").get("recommendation").getAsString()));
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
from __future__ import print_function
from telesign.score import ScoreClient

customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
api_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="

phone_number = "Your test phone number with no special characters or spaces."
account_lifecycle_event = "create"

data = ScoreClient(customer_id, api_key)
response = data.score(phone_number, account_lifecycle_event)

if response.ok:
    print("Phone number {} has a '{}' risk level and the recommendation is to '{}' the transaction.".format(
        phone_number,
        response.json['risk']['level'],
        response.json['risk']['recommendation']))
require 'telesign'

customer_id = 'FFFFFFFF-EEEE-DDDD-1234-AB1234567890'
api_key = 'EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=='

phone_number = 'Your test phone number with no special characters or spaces.'
account_lifecycle_event = 'create'

score_client = Telesign::ScoreClient.new(customer_id, api_key)
response = score_client.score(phone_number, account_lifecycle_event)

if response.ok
    puts "Phone number %s has a '%s' risk level and the recommendation is to '%s' the transaction." %
        [phone_number,
        response.json['risk']['level'],
        response.json['risk']['recommendation']]
end
<?php
require __DIR__ . "/../../vendor/autoload.php";
use telesign\sdk\score\ScoreClient;
$customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
$api_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
$phone_number = "Your test phone number with no special characters or spaces.";
$account_lifecycle_event = "create";
$data = new ScoreClient($customer_id, $api_key);
$response = $data->score($phone_number, $account_lifecycle_event);
if ($response->ok) {
  echo "Phone number $phone_number has a '{$response->json["risk"]["level"]}' risk level"
  . " and the recommendation is to '{$response->json["risk"]["recommendation"]}' the transaction.";
}
using System;

namespace Telesign.Example.Score
{
    class CheckPhoneNumberRiskLevel
    {
        static void Main(string[] args)
        {
            string customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
            string apiKey = "EXAMPLETE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

            string phoneNumber = "Your test phone number with no special characters or spaces.";

            string accountLifecycleEvent = "create";

            try
            {
                ScoreClient scoreClient = new ScoreClient(customerId, apiKey);
                RestClient.TelesignResponse telesignResponse = scoreClient.Score(phoneNumber, accountLifecycleEvent);

                if (telesignResponse.OK)
                {
                    Console.WriteLine(string.Format("Phone number {0} has a '{1}' risk level and the recommendation is to '{2}' the transaction.",
                        phoneNumber,
                        telesignResponse.Json["risk"]["level"],
                        telesignResponse.Json["risk"]["recommendation"]));
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e);
            }

            Console.WriteLine("Press any key to quit.");
            Console.ReadKey();
        }
    }
}
curl -X POST https://rest-api.telesign.com/v1/score/<complete_phone_number> \
-d account_lifecycle_event="sign-in" \
-u "CUSTOMER_ID":"API_KEY"

This quick start describes how to use TeleSign SDKs to check a phone number's risk level using Score. You can use this information to decide what you want to do with the phone number. If you find that the phone number's risk level is too high, you can block that number from signing up for an account, or completing other kinds of transactions in your system. If a phone number is somewhat high, you could flag it as something to keep an eye on. Finding a phone number's score is an easy way to cut down on fraudster attacks while still ensuring good end users can access your products and services.

Requirements

For this quick start, the following is required:

  • Customer ID - Obtain this for your account by logging in to portal.telesign.com
  • API key - Obtain this for your account by logging in to portal.telesign.com
  • SDK - Download the SDK from TeleSign's GitHub repository for your selected language:
  • Language Version
    • Node.js - 6+
    • Java - 7+
    • Python - 2.7+
    • Ruby - 2+
    • PHP - 5.6+
    • C# - 4.5+
  • Purchased Phone Number - You must purchase a phone number in TelePortal to use with this API.

📘

NOTE:

If you do not have a customer ID, sign up for TeleSign's Free Trial.

Install the SDK

  1. Log in to GitHub and choose the SDK in your preferred language:
  1. Download or clone the repository. If you download it, extract the repository from the .ZIP file.
  2. To install the SDK, do the following:
npm install telesignsdk -save
compile 'com.telesign:telesign:[current_version]'
<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
/* Add this to your packages.config file. */
<package id="Telesign" version="(insert latest version)" targetFramework="(insert framework)" />

Check Phone Number Risk Level with Score

This section explains how to check a phone number's risk level using Score. The sample code provided earlier is broken out into pieces and explained below.

In this code sample, you provide your customer ID and API key to authenticate yourself with TeleSign. Then you create a ScoreClient object and use the score method to check a phone number that you specify. You then display information about the phone number check such as risk level and what the recommendation for that risk level is, along with a formatted version of the json response.

  1. Begin by adding statements for including the appropriate part of the TeleSign SDK and any additional language specific functions you may need.
var TeleSignSDK = require('telesignsdk');
package com.telesign.example.score;

import com.telesign.RestClient;
import com.telesign.ScoreClient;
from __future__ import print_function
from telesign.score import ScoreClient

#If you are working with a version of Python 3, you do not need the first import
#statement (`from __future__ import print_function`).
require 'telesign'
<?php
require __DIR__ . "/../../vendor/autoload.php";
use telesign\sdk\score\ScoreClient;
using System;
  1. Insert values for each of the items from customer_id/customerId through account_lifecycle_event. For account_lifecycle_event, you choose the kind of event that prompted you to check the phone number. You can choose between:
  • create - For the creation of a new account.
  • sign-in - For when an end user signs in to their account.
  • transact - For when an end user completes a transaction within their account.
  • update - For when an update is performed, such as an update of account information or similar.
  • delete - For when an account is deleted.
const customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"; // Todo: find in portal.telesign.com
const apiKey = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="; // Todo: find in portal.telesign.com
const rest_endpoint = "https://rest-api.telesign.com"; 
const timeout = 10*1000; // 10 secs

const client = new TeleSignSDK( customerId,
    apiKey,
    rest_endpoint,
    timeout // optional
    // userAgent
);

const phoneNumber = "Your test phone number with no special characters or spaces.";
const accountLifeCycleEvent = "create";
public class CheckPhoneNumberRiskLevel {

    public static void main(String[] args) {

        String customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
        String apiKey = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

        String phoneNumber = "Your test phone number with no special characters or spaces.";
        String accountLifecycleEvent = "create";
customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
api_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="

phone_number = "Your test phone number with no special characters or spaces."
account_lifecycle_event = "create"
customer_id = 'FFFFFFFF-EEEE-DDDD-1234-AB1234567890'
api_key = 'EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=='

phone_number = 'Your test phone number with no special characters or spaces.'
account_lifecycle_event = 'create'
$customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
$api_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
$phone_number = "Your test phone number with no special characters or spaces.";
$account_lifecycle_event = "create";
namespace Telesign.Example.Score
{
    class CheckPhoneNumberRiskLevel
    {
        static void Main(string[] args)
        {
            string customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
            string apiKey = "EXAMPLETE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

            string phoneNumber = "Your test phone number with no special characters or spaces.";

            string accountLifecycleEvent = "create";
  1. Instantiate a ScoreClient object containing your customer ID and API key. For node.js, you will use this step to set up a console and declare a function that will later be used to instantiate a Score client object.
console.log("## ScoreClient.score ##");

function score_callback(error, response_body) {
    if (error === null) {
        console.log(`Score response for phone number: ${phoneNumber}` +
            ` => code: ${response_body['status']['code']}` +
            `, description: ${response_body['status']['description']}`);
    } else {
        console.error("Unable to get score. " + error);
    }
}
        try {
            ScoreClient scoreClient = new ScoreClient(customerId, apiKey);
data = ScoreClient(customer_id, api_key)
score_client = Telesign::ScoreClient.new(customer_id, api_key)
$data = new ScoreClient($customer_id, $api_key);
            try
            {
                ScoreClient scoreClient = new ScoreClient(customerId, apiKey);
  1. Use Score with a phone number you specify and store the results of your check on the phone number in response. For node.js, use this step to instantiate a Score client object and pass it the function you defined in the last step.
client.score.score(score_callback, phoneNumber, accountLifeCycleEvent);
            RestClient.TelesignResponse telesignResponse = scoreClient.score(phoneNumber, accountLifecycleEvent, null);
response = data.score(phone_number, account_lifecycle_event)
response = score_client.score(phone_number, account_lifecycle_event)
$response = $data->score($phone_number, $account_lifecycle_event);
                RestClient.TelesignResponse telesignResponse = scoreClient.Score(phoneNumber, accountLifecycleEvent);
  1. For this example, a print statement shows you the components of the Score result on the phone number. You can see your phone number's risk level and what recommendation is associated with a particular risk level. For more information about different risk levels, refer to the Score and Risk Levels section of the Score API - Get Started page.
//If all goes well, you should already get the risk level and risk recommendation 
//information back. 
            if (telesignResponse.ok) {
                System.out.println(String.format("Phone number %s has a '%s' risk level and the recommendation is to '%s' the transaction.",
                        phoneNumber,
                        telesignResponse.json.getAsJsonObject("risk").get("level").getAsString(),
                        telesignResponse.json.getAsJsonObject("risk").get("recommendation").getAsString()));
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
if response.ok:
    print("Phone number {} has a '{}' risk level and the recommendation is to '{}' the transaction.".format(
        phone_number,
        response.json['risk']['level'],
        response.json['risk']['recommendation']))
if response.ok
    puts "Phone number %s has a '%s' risk level and the recommendation is to '%s' the transaction." %
        [phone_number,
        response.json['risk']['level'],
        response.json['risk']['recommendation']]
end
if ($response->ok) {
  echo "Phone number $phone_number has a '{$response->json["risk"]["level"]}' risk level"
  . " and the recommendation is to '{$response->json["risk"]["recommendation"]}' the transaction.";
}
                if (telesignResponse.OK)
                {
                    Console.WriteLine(string.Format("Phone number {0} has a '{1}' risk level and the recommendation is to '{2}' the transaction.",
                        phoneNumber,
                        telesignResponse.Json["risk"]["level"],
                        telesignResponse.Json["risk"]["recommendation"]));
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e);
            }

            Console.WriteLine("Press any key to quit.");
            Console.ReadKey();
        }
    }
}
  1. If everything works correctly, you should get risk level and risk recommendation information about a phone number you specified. You can use this information to decide whether to block the phone number or allow it.

Code it Without the SDK

If you want to write your own code, you will need to handle authentication yourself. You need the following documents:


Did this page help you?