Want to provide feedback?

Write to docs@telesign.com.

Get Started with the Score API

This page includes general requirements and service details for this API, as well as instructions on how to use all of its actions.

Looking for Insights reason codes? Check out Insights Reason Code Mappings.

Reference Page

POST /score/{complete_phone_number}

Full technical details for the API, including explanations of each request parameter and response property.

General Requirements

Request Requirements

  • Endpoint: https://rest-ww.telesign.com/v1/score
  • Authentication: Basic (easiest to implement) or Digest
  • Encoding: Accepts only UTF-8 unicode characters as inputs.
  • MIME Type: application/x-www-form-urlencoded
  • Required Headers: Content-Type - application/x-www-form-urlencoded

Response Details

  • MIME Type: application/json

Understanding Your Score and Related Details

The score returned for a phone number is a measure of the risk involved with conducting online business transactions with its registered owner. The score ranges from zero to 1000, with a higher score indicating a higher risk.

The other details related to the score that are returned with it are:

  • Level: An assessment of the level of risk involved with conducting business with the person registered to this phone number.
  • Recommendation: 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).

What is Different About Score 2.0?

Requests to the API can be configured to return either a Score 2.0 result or the legacy Score 1.0 result.

Score 2.0 differs from the original Score in two critical ways:

  • Richer Datasets: Score 2.0 has access to richer datasets, allowing us to use advanced machine learning techniques to discover new patterns.
  • Improved Score Scale: The discovery of more behavioral patterns in Score 2.0 has allowed us to augment existing risk zones (medium, high), while also creating a new risk zone (very low). The users in this new zone have displayed human-like behavior on international telco networks and so have a high likelihood of being genuine users.
CAUTION

Because of the differences described above between Score 1.0 and 2.0, do not use these two response types within the same integration. Although we have kept the API endpoint the same for ease of migration, the new score output is both a substantial improvement and a substantial change. Be sure to do your full due diligence on the effects of using Score 2.0 on your integration, so you can get maximum value from this upgrade. Our customer facing teams are ready to assist you with this integration change.

Insights

Insights is a package of data points included in Score 2.0 results with more in-depth details related to the risk presented by the phone number. Insights Reason Code Mappings provides more detail about each available insight.

Score Scales

Use the appropriate scale below for interpreting the score, based on which version of Score you used to make your request.

Score Risk Level Recommendation Comments
0-80 low allow users with insufficient risk indicators
81-450 very low allow users with significant confidence-building behavior on-network
451-500 medium-low flag suspicious users
501-600 medium flag suspicious users
601-800 high block risky users
801-1000 very high block risky users

Actions

Request a Reputation Score for a Phone Number

Reference Page: POST /score/{complete_phone_number}

Use this action to obtain a reputation score and other relevant information for a specified phone number. The service also provides the data elements you would normally see returned by the PhoneID API.

The reference page includes full details for each request parameter and response property.

Try It

If you have been granted access and credentials for the Score API, you can try a test request in the API Explorer below. You can also get a code snippet for the request.

  1. Click the Auth tab and for Username add your customer ID. For Password add your API key.
  2. Click the Settings tab. In the complete_phone_number field enter the phone number you want a score for, including the country code but with no special characters or spaces.
  3. Click the Body tab to modify your request parameters, if desired. See the reference page POST /score/{complete_phone_number} for full parameter details.
  4. Click Send.
  5. Click the Code Generation tab and use the Language and Library menus to choose the language you want your code snippet in.
Caution

Using your account credentials in the API Explorer to request a score results in your account being charged for the transaction.

Score API Explorer
NOTE: The response time shown is not indicative of regular transmission rates, and only applies to the Score API Explorer.
Send requests directly from the browser (CORS must be enabled)
Path Params
1 path param not set
complete_phone_number
$$.env
No $$.env variables are being used in this request.

Examples

Example 1: Success

Request
application/x-www-form-urlencoded
POST /v1/score/15555551212 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic pPF9MAXw9ssP0rkk8sbWf18Fny5Vgqi4F1owcHADr8LXk8PMWIvWqeg419NNXmBtMkaTJi3U5IOhOrNOY1ZXdBv3pLZxn08Rah8mMTGv623wYqmmNRcI5adDVnYbm1ejt2E4JCiMmOFahwcNcy844cpz8dTEWMVo1XthlYf=
Host: rest-ww.telesign.com

account_lifecycle_event=create&request_risk_insights=true
Response (body only)
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
  },
  "risk_insights": {
    "status": 800,
    "category": [
      10002
    ],
    "a2p": [
      20001,
      20101,
      21002
    ],
    "p2p": [
      30004,
      30101,
      30201,
      30302,
      31008
    ],
    "number_type": [
      40005,
      40011
    ],
    "ip": [
      50001,
      50004
    ],
    "email": [
      60003,
      60006
    ]
  }
}

Example 2: Failure

If something goes wrong with your request, the response you get looks like the example below. The exact response properties you see will depend on the type of failure.

Request
application/x-www-form-urlencoded
POST /v1/score/15555551212 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic pPF9MAXw9ssP0rkk8sbWf18Fny5Vgqi4F1owcHADr8LXk8PMWIvWqeg419NNXmBtMkaTJi3U5IOhOrNOY1ZXdBv3pLZxn08Rah8mMTGv623wYqmmNRcI5adDVnYbm1ejt2E4JCiMmOFahwcNcy844cpz8dTEWMVo1XthlYf=
Host: rest-ww.telesign.com

account_lifecycle_event=&request_risk_insights=true
Response (body only)
application/json
{
  "reference_id": "B56C5CAC2964010889502ADC56641615",
  "status": {
    "code": 11003,
    "description": "Invalid value for parameter account_lifecycle_event.",
    "updated_on": "2017-03-28T23:05:48.398146Z"
  }
}

Next Steps

Check out some other related pages: