Request a Reputation Score

The fastest way to get your first reputation score for a phone nuber is to try out the Score API using TeleSign’s Score API Explorer below. If you have your credentials, follow the instructions to use TeleSign’s Score API. You will also be able to get a code snippet for the request in the language of your choice.

Score API Explorer
NOTE: When using the Score API Explorer, you will be charged your contracted rate for each transaction. The time shown in ms 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.

Use these instructions with the Score API Explorer (above) to send a request for a reputation score for a phone number. You will also get a code snippet for making the request in the language of your choice.

  1. Click the Auth [basic] tab and for Username add your customer ID. For Password add your API key.
  2. Click the Settings tab and in the complete_phone_number field, enter your phone number with the country code and no special characters or spaces.
  3. Click the Body tab and for account_lifecycle_event, the field is populated with create. This parameter is required. (See available parameters on the API reference page - POST v1/score.)
  4. Click Send.
  5. Click the Code Generation tab and use the Language and Library drop-downs to choose the language you want your code snippet in.

Congratulations! You’ve sent your first reputation score request for a phone number using TeleSign’s Score API and generated your first code snippet!

You can see more about available parameters for requests on the Score Request (POST v1/score) page.

The rest of this page provides details about TeleSign’s Score API. You can choose from these options:

Score API Information

This section provides general information about the Score API.

  • The URI is https://rest-api.telesign.com/v1/score/<complete_phone_number>
  • Authentication - You can authenticate with basic or digest authentication.
  • Use UTF-8 encoded unicode characters as inputs for all TeleSign APIs.
  • Content-Type is application/x-www-form-urlencoded

For all available parameters you can include in your request, refer to Score Request (POST v1/score).

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
POST https://rest-api.telesign.com/v1/score/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:n135MeEOwaWnkWVFWG0DFULtRLY=
Content-Type: application/x-www-form-urlencoded

account_lifecycle_event=create

When you send the number, the score and other details ab out 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.

  • PhoneID API - You may want to review the PhoneID API to learn more about what is returned in a Score response. Score responses include all standard PhoneID content.
  • Score API - Review the Score API parameters and what comes back in a response.