Phone Reputation API

Overview

Block and filter out spam. Know in real time when a number is behaving badly across the voice and SMS channels in real-time with an easy to act on reputation level of 1 – 4.

Using a RESTful GET API request, you’ll receive reputation level and also details including what spam, scams and fraud activities are associated with the phone number. You can find more details about Phone Reputation here.

Get a free API key Not a developer?

Request

A well-formatted request looks like:

Copy
https://proapi.whitepages.com/3.0/phone_reputation?phone=2282200226&api_key=KEYVAL

Request parameters

ParametersDescriptionExamples
api_keySee here to acquire an API key. REQUIRED
phoneContains a raw unparsed or a formatted phone number. REQUIRED

2069735184 or 12069735184 or 206-601-3561 or +12066013561

phone.country_hintContains the ISO-3166-1 alpha-2 code for the phone_number

US or MX or ZA

Response

A Phone Reputation response is formatted as follows.

Click the # to see that field used within the example JSON response.

Phone Reputation Response

1idString

Copy
"id": "Phone.39456fef-a2e0-4b08-cfe3-bc7128b7100f.Durable"
Phone number id.

2phone_numberString

Copy
"phone_number": "2282200226"
Normalized input phone number in local format.

3reputation_levelInteger

Copy
"reputation_level": 4

A 1-4 score on the likelihood of this phone number being spammy. 1 indicates high confidence that this phone number has not been associated with spam/risky behavior, 4 indicates very high confidence that this is a spammy/risky phone number.

4reputation_detailsObject

An object describing spam/risky behavior this number has been associated with. Each object consists of:

scoreInteger

Copy
"score": 91
A 0-100 score on the likelihood of this phone number being associated with a particular type of spam or scam.

typeString

Copy
"type": "RiskType"
Type of behavior associated with this phone number. Values are NotSpamType, NuisanceType, MixedType, RiskType, UnrecognizedType, UncertainType.

categoryString

Copy
 "category": "TechSupportScam"
Category of spam/risk associated with the phone. Categories identified include:

  • NotSpam
  • GeneralSpam
  • DebtCollector
  • Political
  • Nonprofit
  • Telemarketer
  • Survey
  • ScamOrFraud
  • Extortion
  • IdentityTheft
  • TollFreeTrafficPumping
  • StolenIdentity
  • IRSScam
  • TaxScam
  • TechSupportScam
  • VacationScam
  • LuckyWinnerScam
5volume_scoreInteger

Copy
"volume_score": 1
A 1-4 score on how active the phone number has been making/receiving calls and sms.

6report_countInteger

Copy
"report_count": 3
Number of reports we have received on this phone number being spam/risky.

7errorObject

Copy
"error": null

An error object which contains name string and message string. For example:
Copy
{
"message": "Could not retrieve entire response",
"name": "PartialError"
}

8warningsArray of strings
Copy
"warnings": []

An array of strings with validation warnings. Possible values are:

  • Invalid Input
  • Missing Input
  • Invalid phone.county_hint value. Only Alpha-2 and Alpha-3 supported

Response

Copy
{
"id": "Phone.39456fef-a2e0-4b08-cfe3-bc7128b7100f.Durable",
"phone_number": "2282200226",
"reputation_level": 4,
"reputation_details": {
"score": 91,
"type": "RiskType",
"category": "TechSupportScam"
},
"volume_score": 1,
"report_count": 3,
"error": null,
"warnings": [ ]
}