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

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.

This quick start includes the following sections:

Requirements

For this quick start, the following is required:

  • customer ID - obtain from your account by logging in to portal.telesign.com (referred to as customer_id in/customerId this document)
  • API key - obtain from your account by logging in to portal.telesign.com (referred to as api_key/apiKey in this document)
  • SDK - Access to 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+
  • Verified Phone Number - To use TeleSign’s free trial, you must verify a phone number before using it.
NOTE:

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

Install the SDK

  1. Obtain your customer ID and API key.
  2. 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 for use, do the following:

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');
  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";
  1. Instantiate a ScoreClient object containing your customer ID and API key (customer_id/customerId and api_key/apiKey). 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);
    }
}
  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);
  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 Scores and Risk Levels section of the Score API page.
//If all goes well, you should already get the risk level and risk recommendation 
//information back. 
  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: