TeleSign Developer Center

Welcome! This resource hub provides documentation and references on API & SDK integration and other product-related information.

Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

Standard Score API

The Score API is a REST API that delivers reputation scoring based on phone number intelligence, traffic patterns, machine learning, and a global data consortium.

READ THIS NOTE:

This documentation is intended for you if you use the Standard versions of TeleSign products. If you are using TeleSign's free trial, you are using Standard TeleSign products.

You use Standard TeleSign products if you log in to your account at portal.telesign.com, use
endpoints that begin with rest-api.telesign.com, and do not have a designated Technical Account Manager (TAM).

If you log in to your account at teleportal.telesign.com, have endpoints that begin with rest.telesign.com or rest-ww.telesign.com, and have a TAM, you need the Score for Enterprise API page instead.

The Score web service provides risk information about a specified phone number alongside the data elements you would normally see returned by the PhoneID API.

Score and risk level details returned:

Item
Example
Description

Level

High

An assessment of the level of risk involved with conducting business with the person registered to this phone number.

Recommendation

Block

Advice on the safest course of action to follow (to either proceed with the online transaction, to proceed with caution, or to not proceed at all).

Score

900

A rating on a scale from 0 to 1000. The higher the score, the higher the risk.

For a complete list of returned levels, refer to section Scores and Risk Levels below.

NOTE:

TeleSign applies machine learning techniques on hundreds of data points from proprietary and commercial data sources to assess the risk associated with doing an online transaction with a phone number.

Implement the Score API with an SDK

TeleSign recommends using one of the SDKs as the SDKs handle authentication for you and are available in Java, Python, Ruby, PHP, and C#.

The following tutorial can help you get started quickly with the Score API:

Additionally, you should review the Request Parameters section and the Response Parameters section, which contains details about the parameters you can include in requests, as well as what parameters are returned in responses.

Authentication

Access to TeleSign web services is restricted. To receive results for any call you make to a TeleSign web service, you must digitally sign your request message with valid credentials. You sign a request by creating a signature and adding it to your message’s Authorization header. The signature is your message authentication code (MAC). When received by TeleSign, the shared secret API key is used to hash details about the message. A successful match results in successful authentication and a response from the TeleSign web service you called.

To get started, you should review the basic steps for setting up authentication. Review the following:

Additionally, for an example of how to implement authentication, you can take a look at how TeleSign does it for the SDKs. Click the link for the appropriate language to see how TeleSign implements authentication.

URI

The Score web service is exposed with a URI of the form:

https://rest-api.telesign.com/v1/score/<complete_phone_number>

Subresource Identifier

complete_phone_number

  • [Required] Your end user’s phone number, as a string of digits without spaces or punctuation, beginning with the country dialing code (for example, “1” for North America).
  • [Example] 15555551212

Supported HTTP Methods

POST

Information Returned
Score returns the following pieces of information:

  • Risk
    • Risk Level
    • Recommendation
    • Score

The following example URI calls the Score web service to run a query on the phone number +1 (555) 555-1212.

https://rest-api.telesign.com/v1/score/15555551212

Request Parameters

POST requests for the Score web service can include the following parameters:

account_lifecycle_event

  • [Required] This parameter allows you to indicate what phase of the lifecycle you are in when you send a transaction. The options for this parameter are:
    • 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.

originating_ip

  • [Optional] Your end user’s IP Address (do not send your own IP address). This value must be in the format defined by the Internet Engineering Task Force (IETF) in the Internet-Draft document titled Textual Representation of IPv4 and IPv6 Addresses.
  • [Example] originating_ip=203.0.113.45

device_id

  • [Optional] Your end user’s device ID. This value is case sensitive, a string, must be created with Unicode characters, and encoded as UTF-8.

account_id

  • [Optional] Your end user’s account ID. This value is case sensitive, a string, must be created with Unicode characters, and encoded as UTF-8.

email_address

  • [Optional] Your end user’s email address. This value is case sensitive, a string, must be created with Unicode characters, and encoded as UTF-8.
POST https://rest-api.telesign.com/score/15555551212 HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:n135MeEOwaWnkWVFWG0DFULtRLY=
Date: Tue, 31 Jan 2017 16:25:37 GMT
Content-Type: application/x-www-form-urlencoded

account_lifecycle_event=create

Response Parameters

The response entity-body contains the following information in JavaScript Object Notation (JSON).

NOTE:

Unless otherwise specified, a missing or unspecified value defaults to null.

reference_id

  • A 32-digit hex value used to identify the web service request. The value is unique to each web service request, is randomly-generated by TeleSign, and is returned in the response message immediately following the web service request.

status

  • An object containing details about the request status.
    ValueDescription
    codeOne of the status codes or error codes may appear here.
    descriptionText describing the status code or error code shown for the code parameter.
    updated_onAn RFC 3339 timestamp indicating when the transaction status was updated

numbering

  • An object containing details about the numbering attributes of the specified phone number. This object contains the following parameters:

    original

    • An object containing details about the original phone number passed to TeleSign’s Score API. It comprises the following data:
      ValueDescription
      phone_numberThe base phone number. This is simply the phone number without the country dialing code.
      complete_phone_numberThe base phone number prefixed with the country dialing code. This forms the subresource identifier part of the Score web service URI.
      country_codeA 1, 2, or 3-digit number representing the country dialing code. For example, the country dialing code for both the U.S.A. and Canada is 1, and the country dialing code for the United Kingdom is 44.

    cleansing

    • An object containing details about how the phone number was cleansed. Phone cleansing corrects common formatting issues in submitted phone numbers. This object contains the following parameters:

      call

      • An object containing cleansing details about a phone number used for receiving voice calls. This object contains the following parameters:
        ValueDescription
        cleansed_codeOne of the phone number cleansing codes describing the cleansing operation TeleSign performed on the phone number. The default value is 100 (meaning no changes were made to the phone number).
        country_codeA 1, 2, or 3-digit number representing the country dialing code. For example, the country dialing code for both the U.S.A. and Canada is 1, and the country dialing code for the United Kingdom is 44.
        max_lengthThe maximum number of digits allowed for phone numbers with this particular country dialing code.
        min_lengthThe minimum number of digits allowed for phone numbers with this particular country dialing code.
        phone_numberThe base phone number. This is simply the phone number without the country dialing code.
      sms
      • An object containing cleansing details about a phone number used for receiving text messages. This object contains the following parameters:
        ValueDescription
        cleansed_codeOne of the phone number cleansing codes describing the cleansing operation TeleSign performed on the phone number. The default value is 100 (meaning no changes were made to the phone number).
        country_codeA 1, 2, or 3-digit number representing the country dialing code. For example, the country dialing code for both the U.S.A. and Canada is 1, and the country dialing code for the United Kingdom is 44.
        max_lengthThe maximum number of digits allowed for phone numbers with this particular country dialing code.
        min_lengthThe minimum number of digits allowed for phone numbers with this particular country dialing code.
        phone_numberThe base phone number. This is simply the phone number without the country dialing code.

phone_type

  • An object containing details about the phone type. This object contains the following parameters:
    ValueDescription
    codeOne of the phone type codes
    descriptionText describing the phone type

carrier

  • An object containing information about the company that provides telecommunications services for the phone number. This object contains the following parameter:

    name

    • A string specifying the name of the carrier. For example: “Verizon”.

risk

  • An object that describes the risk score for the phone number specified in the request; it contains the following parameters:
    ValueDescription
    levelA string indicating the severity of the risk.
    recommendationA string indicating the action that TeleSign recommends that you take based on the risk score
    scoreOne of the scores and risk levels values
{
   "reference_id": "B567DC5D1180011C8952823CF6B40773", 
   "status": {
      "updated_on": "2017-02-01T00:33:34.860418Z", 
      "code": 300, 
      "description": "Transaction successfully completed"
   }, 
   "numbering": {
      "original": {
         "complete_phone_number": "15555551212", 
         "country_code": "1", 
         "phone_number": "5555551212"
      }, 
     "cleansing": {
       "call": {
         "country_code": "1", 
         "phone_number": "5555551212", 
         "cleansed_code": 105, 
         "min_length": 10, 
         "max_length": 10
       }, 
       "sms": {
         "country_code": "1", 
         "phone_number": "5555551212", 
         "cleansed_code": 105, 
         "min_length": 10, 
         "max_length": 10
       }
     }
   }, 
  "phone_type": {
    "code": "8", 
    "description": "INVALID"
  }, 
  "location": {
    "city": "Countrywide", 
    "state": null, 
    "zip": null, 
    "metro_code": null, 
    "county": null, 
    "country": {
      "name": "United Kingdom", 
      "iso2": "GB", 
      "iso3": "GBR"
    }, 
    "coordinates": {
      "latitude": null, 
      "longitude": null
    }, 
    "time_zone": {
      "name": null, 
      "utc_offset_min": "0", 
      "utc_offset_max": "0"}
  }, 
  "carrier": {
    "name": "Telefonica UK Limited"
  }, 
  "risk": {
    "level": "high", 
    "recommendation": "block", 
    "score": 959
  }
}

Request Headers

This section provides a summary of required and optional headers for a request. For details about how to use them for proper authentication, review the Authentication page. For more details about these headers, review the section Standard and TeleSign Specific Headers of the Authentication page. If you are using an SDK, you can skip ahead to the section Request Parameters.

General Headers

  • Content-Type - Required for POST requests. Ignored for GET requests, but you must mark its position with a newline for StringToSign.
  • Date - Required unless you include X-TS-Date. If you do not include the Date header value, you must mark its position with a newline character for StringToSign.

Request Headers

TeleSign-Specific HTTP Headers

  • X-TS-Date - Optional, you may use this instead of the Date header.
  • X-TS-Nonce - Optional, specifies a unique, random nonce string. You can include this header to provide additional protection against malicious replay attacks.
  • X-TS-Auth-Method - Required for HMAC-SHA256.

Response Headers

The TeleSign server returns the following headers for this subresource:

Allow

  • Indicates the HTTP methods that the resource supports. The allowed method for /v1/score/ is POST.

Content-Type

  • Indicates the content type of the response entity-body. TeleSign web services always use a value of application/json.
HTTP/1.1 200 OK
Date: Wed, 01 Feb 2017 00:33:34 GMT
Server: Apache
Content-Length: 1174
Allow: POST
Content-Type: application/json

Examples

This section contains all the examples provided in the document earlier.

POST https://rest-api.telesign.com/score/15555551212 HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Authorization: Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:n135MeEOwaWnkWVFWG0DFULtRLY=
Date: Tue, 31 Jan 2017 16:25:37 GMT
Content-Type: application/x-www-form-urlencoded

account_lifecycle_event=create
HTTP/1.1 200 OK
Date: Wed, 01 Feb 2017 00:33:34 GMT
Server: Apache
Content-Length: 1174
Allow: POST
Content-Type: application/json
{
   "reference_id": "B567DC5D1180011C8952823CF6B40773", 
   "status": {
      "updated_on": "2017-02-01T00:33:34.860418Z", 
      "code": 300, 
      "description": "Transaction successfully completed"
   }, 
   "numbering": {
      "original": {
         "complete_phone_number": "15555551212", 
         "country_code": "1", 
         "phone_number": "5555551212"
      }, 
     "cleansing": {
       "call": {
         "country_code": "1", 
         "phone_number": "5555551212", 
         "cleansed_code": 105, 
         "min_length": 10, 
         "max_length": 10
       }, 
       "sms": {
         "country_code": "1", 
         "phone_number": "5555551212", 
         "cleansed_code": 105, 
         "min_length": 10, 
         "max_length": 10
       }
     }
   }, 
  "phone_type": {
    "code": "8", 
    "description": "INVALID"
  }, 
  "location": {
    "city": "Countrywide", 
    "state": null, 
    "zip": null, 
    "metro_code": null, 
    "county": null, 
    "country": {
      "name": "United Kingdom", 
      "iso2": "GB", 
      "iso3": "GBR"
    }, 
    "coordinates": {
      "latitude": null, 
      "longitude": null
    }, 
    "time_zone": {
      "name": null, 
      "utc_offset_min": "0", 
      "utc_offset_max": "0"}
  }, 
  "carrier": {
    "name": "Telefonica UK Limited"
  }, 
  "risk": {
    "level": "high", 
    "recommendation": "block", 
    "score": 959
  }
}

Example Bad Request

POST https://rest-api.telesign.com/score/15555551212 HTTP/1.1
X-TS-Auth-Method: HMAC-SHA256
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:n135MeEOwaWnkWVFWG0DFULtRLY=
Date: Tue, 31 Jan 2017 16:25:37 GMT
Content-Type: application/x-www-form-urlencoded

account_lifecycle_event=creat
HTTP/1.1 400 Bad Request
Date: Wed, 01 Feb 2017 00:49:22 GMT
Server: Apache
Content-Length: 193
Allow: POST
Content-Type: application/json
{   
    "reference_id": "B56C5CAC2964010889502ADC56641615",
    "status": {   
       "code": 11003,
       "description": "Invalid value for parameter account_lifecycle_event.",
       "updated_on": "2017-03-28T23:05:48.398146Z"
		}
}

Scores and Risk Levels

A phone number’s score is a measure of the risk involved with conducting online business transactions with its registered owner.

The score is a rating on a scale from zero to a thousand, and the scale is divided into five successively increasing ranges. Scores correlate with the risk level associated with the range they fall into, and each risk level has an associated recommendation.

Score
Risk Level
Recommendation

801-1000

high

block

601-800

medium-high

block

401-600

medium

flag

201-400

medium-low

allow

0-200

low

allow

-1

neutral

N/A

Country Codes and Dialing Codes

If you need to know country and dialing codes, review the Country Codes and Dialing Codes section on the Codes, Languages, Time Zones page.

Status Codes

For Score, the following codes are returned for the code parameter if your transaction was a success:

Code
Description
Detail

300

Transaction successfully completed

The system was able to obtain all of the requested data for Score.

301

Transaction partially completed

The system was able to obtain some of the data for Score, but not all of it.

HTTP Codes Mapped to Error Codes

For a general list of HTTP codes and how they map to error codes generated by the Score API, review the HTTP Codes Mapped to Error Codes section on the Codes, Languages, Time Zones page. These codes are returned for the code parameter if your transaction had issues.

Phone Number Cleansing Codes

For a general list of phone number cleansing codes review the Phone Number Cleansing Codes section on the Codes, Languages, Time Zones page.

Phone Type Codes

For a general list of phone type codes review the Phone Type Codes section on the Codes, Languages, Time Zones page.

Time Zones

For a general list of time zones you can use review the Time Zones section on the Codes, Languages, Time Zones page.

Standard Score API