- About the IPQS APIs
- Proxy & VPN Detection API
- Email Verification API
- Phone Number Validation API
- Malicious URL Scanner API
- Device Fingerprint API
- Mobile Device Fingerprinting SDK
- Gaming Fraud Detection SDK
- Dark Web Leak API
- Malware File Scanner API
- Request List API
- Fraud Reporting API
- Account Management APIs
- Bulk Validation CSV
- Allowlist Blocklist APIs
- Plugins Platforms Integrations
- IP Reputation Database
- IP Address Abuse Feed
- Email Verification Database
-
Custom Integrations
- Getting Started
- Authentication
- Refresh Secret
- IP & Proxy Checks
- Email Verification Checks
- Phone Number Validity Checks
- Device Tracker
- List Device Trackers
- Device Tracker Statistics
- Login Tokens
- Overview Statistics
- Recent Proxy Statistics
- Recent Email Statistics
- Fraud Reporting
- Retrieve Requests by ID
- Country List API Documentation
- Release Notes
Phone Number Validity Checks
Rate this article:
Select all that apply:
Email:
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:
https://www.ipqualityscore.com/webhooks/ExampleIntegration/json/phone_check
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 |
| 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 |
transaction_details fields
| 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 |
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 |
| 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 |
transaction_details fields
| 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 |
// 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.";
}