Request a Reputation Score

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

Use these instructions with the Score API Explorer 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. Open the reference page for the POST /v1/score/{complete_phone_number} endpoint.
  2. Under the AUTHENTICATION header in the right panel of the page, put your Customer ID in the username field and your API key in the password field.
  3. Under the PATH PARAMS header in the middle panel of the page, enter the complete phone number (including country code) that you want information about in the complete_phone_number field. Do not include any special characters or spaces.
  4. Under the FORM DATA header in the middle panel of the page, enter create for the account_lifecycle_event field. You can also enter any of the other enumerated values for this field listed on the reference page, if you prefer.
  5. Click Try It! in the right panel to see your transaction. You will be charged the standard rate for your transaction, and you are subject to all compliance rules as appropriate for your transaction.
  6. If you want you can also click the copy icon to the left of Try It! to copy the code snippet displayed. To change the programming language of the snippet, select one of the options under the LANGUAGE header in the right sidebar.

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

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](/standard/docs/authentication#basic-authentication
    /standard/docs/authentication#digest-authentication) 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.

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

Did this page help you?