Get Started

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:

LevelHighAn assessment of the level of risk involved with conducting business with the person registered to this phone number.
RecommendationBlockAdvice 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).
Score900A rating on a scale from 0 to 1000. The higher the score, the higher the risk.



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<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 page.

For a list of available parameters you can send in your request, see the 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.

ScoreRisk LevelRecommendation

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.

POST Request Example

Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:n135MeEOwaWnkWVFWG0DFULtRLY=
Content-Type: application/x-www-form-urlencoded

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

Example Response Body

  "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.

Did this page help you?