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/2.2/phone.json?phone_number=2282200226&api_key=KEYVAL

Request parameters

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

2069735184 or 12069735184 or 206-601-3561

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

US or MX or ZA

As noted except for api_key and phone_number most parameters are optional. If you want the phone reputation results tuned for your use case, phone_event_type and phone_event_receiving_number are a requirement.

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":{
"key":"Phone. 39456fef-a2e0-4b08-cfe3-bc7128b7100f.Durable",
"type":"Phone"
}
The entity id

2reputationObject

An array of every spam/risky behavior this number has been associated with. Each array element consists of:

levelNumber

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

detailsObject

An array of every spam/risky behavior this number has been associated with. Each array element consists of:

score

Number

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

type

String

Copy
"type": "risk"
Type of behavior associated with this phone. Values are ‘NotSpam’, ‘Spam’, ‘Risk’ or ‘NotApplicable’, based on the behavior associated with the phone.

category

String

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

  • NotSpam
  • DebtCollector
  • Telemarketer
  • PoliticalCall
  • PhoneSurvey
  • Phishing
  • Extortion
  • IRS Scam
  • Tax Scam
  • Tech Support Scam
  • Vacation Scam
  • Lucky Winner Scam
  • Scam
  • NonProfit
  • Robocaller
  • TollFree Pumping
  • OtherSpam
volume_scoreNumber

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

report_countNumber

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

Example

Request

Copy
https://proapi.whitepages.com/2.2/phone.json?phone_number=2282200226&api_key=KEYVAL

Response

Copy
{
"results":[
{
"id":{
"key":"Phone. 39456fef-a2e0-4b08-cfe3-bc7128b7100f.Durable",
"type":"Phone"
},
"reputation":{
"level":1
"details":[
{
"score": 95,
"type": "risk",
"category": "unknown"
},
]
"volume_score": 1
"report_count": 2
},
],
"messages":[]
}