Want to provide feedback?

Write to docs@telesign.com.

Get Started with the 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.

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.

This page provides instructions and references for features of the Score API.

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.

General Information

All requests submitted for the Score API:

  • Can be authenticated with Basic (easiest to implement) and Digest
  • Use https://rest-ww.telesign.com/v1/score/<complete_phone_number> as the endpoint. The complete phone number includes the country code and has no special characters or spaces.
  • Accept only UTF-8 encoded unicode characters as inputs.
  • Use Content-Type application/x-www-form-urlencoded in request headers.

Request a Reputation Score for a Phone Number

For quick instructions about how to request a reputation score for a phone number, refer to the Request a Reputation Score for a Phone Number page.

For a list of available parameters you can send in your request, see the Score Request (POST v1/score) page.

Score 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
-1 neutral N/A

Phone Number Cleansing Codes

Phone number cleansing codes describe what was done (if anything) to cleanse a phone number you submitted to the Score API. You can see a complete list of available codes on the Codes, Languages, and Time Zones page under the Phone Number Cleansing Codes section.

Phone Type Codes

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

Score API Examples

This section provides examples of requests and responses using the Score API.

You use a POST request to submit the phone number you want to receive a score back for.

Example POST Request with Score
POST https://rest-ww.telesign.com/v1/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

When you send the number, the score and other details about the phone number come back in the body of the response:

Example Response from Score API
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
  }
}

If something goes wrong with your request, the response you get looks like this:

Example Error Response
{
  "reference_id": "B56C5CAC2964010889502ADC56641615",
  "status": {
    "code": 11003,
    "description": "Invalid value for parameter account_lifecycle_event.",
    "updated_on": "2017-03-28T23:05:48.398146Z"
  }
}

Next Steps

This section offers some suggestions for next steps to take.