<< Back to Categories

Phone Number Validity Checks

About Phone Number Validity Checks in Custom Integrations

This API endpoint allows you to perform Phone Number Validation checks on behalf of your users in an almost identical fashion to our standard API structure.

API Request URL

Warning: For security reasons, you should only call this API server-side.

You can use the following URL to submit phone numbers to the phone number validation API:

Request Parameters

Parameter	Description	Example Value / Format
key	Required. Your site's domain or the domain that requested this integration.	google.com
secret	Required. Your user's current secret created during the authentication process.	char(128)
phone	Required. The phone number you wish to validate. If you do not supply a country parameter as well your phone number must include the full country code.	integer or formatted phone number
strictness	How in depth (strict) do you want this reputation check to be? Stricter checks may provide a higher false-positive rate. We recommend starting at "0", the lowest strictness setting, and increasing to "1" or "2" depending on your levels of fraud.	integer, 0 - 2
country (recommended)	You can optionally provide us with the default country or countries this phone number is suspected to be associated with. Our system will prefer to use a country on this list for verification or will require a country to be specified in the event the phone number is less than 10 digits.	string or array of strings

Response Parameters

Note: Only JSON responses are available from this API.

Parameter

Description

Format

valid

Is the phone number properly formatted and considered valid based on assigned phone numbers available to carriers in that country?

boolean

active

Is this phone number a live usable phone number that is currently active?

boolean, null

formatted

The phone number formatted in the international dialing code. N/A if not formattable.

string

local_format

The phone number formatted in the country's local routing rules with area code. N/A if not formattable.

string

fraud_score

The IPQS risk score which estimates how likely a phone number is to be fraudulent. Scores 85+ are high risk.

integer, 0 - 100

recent_abuse

Has this phone number been associated with recent or ongoing fraud?

boolean, null

VOIP

Is this phone number a Voice Over Internet Protocol (VOIP) or digital phone number?

boolean, null

prepaid

Is this phone number associated with a prepaid service plan?

boolean, null

risky

Is this phone number associated with fraudulent activity, scams, robo calls, fake accounts, or other unfriendly behavior?

boolean, null

carrier

The carrier (service provider) this phone number has been assigned to or "N/A" if unknown.

string

line_type

The type of line this phone number is associated with (Toll Free, Mobile, Landline, Satellite, VOIP, Premium Rate, Pager, etc...) or "N/A" if unknown.

string

country

The two character country code for this phone number.

string

region

Region (state) of the phone number if available or "N/A" if unknown.

string

city

City of the phone number if available or "N/A" if unknown.

string

zip_code

Zip or Postal code of the phone number if available or "N/A" if unknown.

string

dialing_code

The 1 to 4 digit dialing code for this phone number or null if unknown.

integer

transaction_details

Additional scoring variables for risk analysis are available when transaction scoring data is passed through the API request. These variables are also useful for scoring user data such as physical addresses, phone numbers, usernames, and transaction details. The data points below are populated when at least 1 transaction data parameter is present in the initial API request. The following transaction variables are "null" when the necessary transaction parameters are not passed with the initial API request. For instance, not passing the "billing_email" will return "valid_billing_email" as null.

object

Key	Description	Format
risk_score	Confidence that this user or transaction is exhibiting malicious behavior. Scores are 0 - 100, with 75+ as suspicious and 90+ as high risk. This value uses different calculations with less weight on the IP reputation compared to the overall "Fraud Score".	Float
valid_billing_address	Physical address validation and reputation analysis.	Boolean
valid_shipping_address	Same as above.	Boolean
valid_billing_email	Light abusive check and reputation analysis for the email address. It is recommended to use our dedicated Email Validation API for deeper analysis.	Boolean
valid_shipping_email	Same as above.	Boolean
leaked_billing_email	Indicates if the email address has recently been exposed or compromised in a database breach.	Boolean
leaked_shipping_email	Same as above.	Boolean
leaked_user_data	Indicates if the user's data (including phone & address) have recently been exposed or compromised in a database breach.	Boolean
risky_billing_phone	Reputation analysis for abusive activity associated with the phone number.	Boolean
risky_shipping_phone	Same as above.	Boolean
valid_billing_phone	Valid & active phone number with the phone carrier (not disconnected).	Boolean
valid_shipping_phone	Same as above.	Boolean
billing_phone_carrier	Phone number provider company such as "AT&T" or "Bell Canada".	String
shipping_phone_carrier	Same as above.	String
billing_phone_line_type	Phone number line type such as "Landline", "Wireless", "Toll Free", "VOIP", "Satellite", "Premium Rate", "Pager".	String
shipping_phone_line_type	Same as above.	String
billing_phone_country	2-letter country code associated with the phone number.	String
shipping_phone_country	Same as above.	String
billing_phone_country_code	Country dialing code associated with the phone number.	Integer
shipping_phone_country_code	Same as above.	Integer
bin_country	Country associated with the credit card BIN.	String
risky_username	Username frequently associated with fraudulent behavior.	Boolean
is_prepaid_card	Status of the credit card as prepaid.	Boolean
fraudulent_behavior	Indicates high risk behavior patterns and a high chance of fraud.	Boolean
phone_name_identity_match	Enterprise Account Feature — Indicates a reverse identity match between the billing phone number and first/last name. Values: "Unknown" - no checks processed, "Match" - positive identity match, "Mismatch" - data matches another user, "No Match" - could not pair identity data.	String
phone_email_identity_match	Enterprise Account Feature — Indicates a reverse identity match between the billing phone number and email address. Values: "Unknown" - no checks processed, "Match" - positive identity match, "Mismatch" - data matches another user, "No Match" - could not pair identity data.	String
phone_address_identity_match	Enterprise Account Feature — Indicates a reverse identity match between the billing phone number and physical address. Values: "Unknown" - no checks processed, "Match" - positive identity match, "Mismatch" - data matches another user, "No Match" - could not pair identity data.	String
email_name_identity_match	Enterprise Account Feature — Indicates a reverse identity match between the billing email address and first/last name. Values: "Unknown" - no checks processed, "Match" - positive identity match, "Mismatch" - data matches another user, "No Match" - could not pair identity data.	String
name_address_identity_match	Enterprise Account Feature — Indicates a reverse identity match between the billing first/last name and physical address. Values: "Unknown" - no checks processed, "Match" - positive identity match, "Mismatch" - data matches another user, "No Match" - could not pair identity data.	String
address_email_identity_match	Enterprise Account Feature — Indicates a reverse identity match between the billing physical address and email address. Values: "Unknown" - no checks processed, "Match" - positive identity match, "Mismatch" - data matches another user, "No Match" - could not pair identity data.	String

message

A generic status message, either success or some form of an error notice.

string

success

Was the request successful?

boolean

errors

Array of errors which occurred while attempting to process this request.

array of strings

EXAMPLE CODE

// URL for this request.
$URL = 'https://www.ipqualityscore.com/webhooks/ExampleIntegration/json/phone_check';

// Configuration items for this request. NOTE: $secret will be user specific not application specific.
$key = 'example.com';
$secret = 'YOUR_API_KEY_HERE';

// The phone number we want to check.
$phone = '18007132618';

// Prepare POST fields.
$fields = array(
	'secret' => $secret,
	'key' => $key,
	'phone' => phone
);
	
// Create CURL.
$curl = curl_init();
	
// Configure CURL
curl_setopt($curl, CURLOPT_URL, $URL);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_POST, 1);

// Set POST Parameters
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($fields));

// Fetch URL
$result = curl_exec($curl);

// GET response code.
$response_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);

// Close CURL
curl_close($curl);
	
// Handle result.
if((int) $response_code === 200){
	// JSON Decode
	$output = json_decode($result, true);
	
	// Was our request successful?
	if($output['success'] === true){
	
		// Print out if this is a valid phone number or not.
		if($output['valid'] === true){
			echo "The phone number ".$phone." is a valid number.";
		} else {
			echo "The phone number ".$phone." is not a valid phone number.";
		}
	
	} else {
		echo $output['message'];
	}
} else {
	echo "There appears to be an unforeseen error. Please contact IPQualityScore support if this persists.";
}

Ready to eliminate fraud?

Start fighting fraud now with 5,000 Free Lookups!

We're happy to answer any questions or concerns.

Chat with our fraud detection experts any day of the week.

Call us at: (800) 713-2618

Schedule a Demo Sign Up