Intelligence - Get started

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

Looking for insights reason codes? Check out Intelligence - Insights reason code mappings.

Reference page

Submit a phone number to evaluate

General requirements

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

Understanding your score and related details

The score returned is a measure of the transaction risk involved with conducting an online business transaction at the current time for the given phone number. 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 transaction risk involved with conducting business at the current time for the given 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 Intelligence 2.0?

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

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

  • Richer Datasets: Intelligence 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 Intelligence 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 Intelligence 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 Intelligence 2.0 on your integration, so you can get maximum value from this upgrade. Our Customer Support Team is ready to assist you with this integration change.

Insights

Insights is a package of data points included in Intelligence 2.0 results with more in-depth details related to the risk presented by the phone number. See Intelligence - Insights reason code mappings for more detail about each available insight.

Score Scales

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

Intelligence 2.0

ScoreRisk LevelRecommendationComments
0-80lowallowtransaction with insufficient risk indicators*
81-450very lowallowtransaction with significant confidence-building behavior on-network**
451-500medium-lowflagsuspicious transaction
501-600mediumflagsuspicious transaction
601-800highblockrisky transaction
801-1000very highblockrisky transaction

* There isn't enough data yet to confirm that there is a high likelihood that the transaction belongs to a genuine user. However, the transaction also doesn't have any indicators that it is a suspicious or risky transaction.

** The transaction is assigned the "very low" risk level because it has enough activity to suggest it likely does belong to a genuine user. This activity means there's more data to use as the basis for the score.

Intelligence 1.0

ScoreRisk LevelRecommendation
0-200lowallow
201-400medium-lowallow
401-600mediumflag
601-800medium-highblock
801-1000highblock

Actions

Request a transaction risk score for a phone number

Reference Page: Submit a phone number to evaluate

Use this action to obtain a transaction risk score for a specified phone number. The service also provides the data elements you would normally see returned by Telesign Phone ID.

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

Try it

If you have been granted access and credentials for Intelligence, you can try a test request using the Submit a phone number to evaluate endpoint. You can also get a code snippet for the request.

🚧

CAUTION:

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

Examples

Example 1: Success

Request

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&originating_ip=203.0.113.45&[email protected]

Response (body only)

{
  "reference_id": "B567DC5D1180011C8952823CF6B40773",
  "status": {
    "updated_on": "2022-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": [
      30201
    ],
    "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

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&originating_ip=203.0.113.45&[email protected]

Response (body only)

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