Phone Reputation API Documentation


IPQS risk analysis tools enable Phone Reputation scoring through an API call. Identify low quality users and fraudulent phone numbers in real-time. Detect temporary or disposable phone numbers as well as phone numbers that have recently been involved in abusive behavior. Phone Reputation screening is a great way to automatically prevent fake accounts and fraudulent behavior.

Phone Reputation API

Phone numbers are validated and analyzed for fraudulent activity by verifying the phone number exists with the carrier, without an SMS message or phone call. Forensic scoring and checks against our high risk user database, powered by Fraud Fusion™, are performed to determine if the phone number has been associated with confirmed reports of fraudulent behavior. Risk analysis for phone numbers will be returned in the "transaction_details" object.

Phone Validation

Each phone number is validated to verify the correct syntax and country code. If a country code is not provided, our system can automatically detect the country code based on the IP address or similar user data. All phone numbers are validated against the local carriers in each country. This service supports phone validation for any country or region including cellular, VOIP, and land lines.

Phone Carrier API

Retrieve the phone carrier and line type with each lookup request. Examples of the carrier include "AT&T", "Verizon", "Vodafone", "T-Mobile", etc. The telephone line type will be classified as "Landline", "Wireless", "Toll Free", or "VOIP". If the carrier is unknown, the data point will return as null.

Country Dial Codes

If the country dial-in code is known, then please supply it with the billing or shipping phone and include "+" symbol at the start of the number. This ensures our system can accurately verify the phone number. If the country code is unknown or the user's input is unvalidated, please pass the billing or shipping number without a "+" symbol. Our algorithms will attempt to detect the country code based on the IP address and billing/shipping country variables.

Scoring Additional User Information

Additional user data such as physical addresses, email addresses, full names, devices, and IP addresses, can also be scored for risk analysis. Please view the Transaction Scoring documentation to learn more.

JSON Phone Reputation Example API Request

The example below incorporates scoring a phone number with an IP address. Phone numbers without a valid country code will assume the country code of the request's IP address. New to IPQS? View our base Proxy Detection API Documentation to get started..

API Lookup with Billing Phone Number
The user's primary information can be passed into the "billing" variables even if a transaction is not taking place. Additional user data can be passed with this request.

API Inputs
Key Expected Values Description
billing_country String (optional) User billing or primary country name or billing country ISO-Alpha2. (EG: United States or US)
billing_phone Number User billing or primary 11 to 14 digit phone number. (If less than 10 digits provided, the country code will be guessed by our AI.)
billing_phone_country_code Number (optional) Country dialing code associated with the billing phone. Typically 1-3 digits.
shipping_country String (optional) User shipping or secondary country name or shipping country ISO-Alpha2. (EG: United States or US)
shipping_phone_country_code Number (optional) Country dialing code associated with the shipping phone. Typically 1-3 digits.
shipping_phone Number (optional) User shipping or secondary 11 to 14 digit phone number. (If less than 10 digits provided, the country code will be guessed by our AI.)
Phone Validation API Response Fields

The following phone validation data points are returned as the API response.

Key Expected Values Description
risky_billing_phone Boolean Reputation analysis for abusive activity associated with the phone number.
risky_shipping_phone Boolean Same as above.
valid_billing_phone Boolean Valid & active phone number with the phone carrier (not disconnected).
valid_shipping_phone Boolean Same as above.
billing_phone_carrier String Phone number provider company such as "AT&T" or "Bell Canada".
shipping_phone_carrier String Same as above.
billing_phone_line_type String Phone number line type such as "Landline", "Wireless", "Toll Free", or "VOIP".
shipping_phone_line_type String Same as above.
billing_phone_country_code Integer Country dial code associated with the phone number.
shipping_phone_country_code Integer Same as above.
Example Code