Custom Integrations - Making Phone Validity Checks Documentation


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

Calling The Phone Number Validation API

https://ipqualityscore.com/webhooks/ExampleIntegration/json/phone_check

Request Parameters
Parameter Description Example Value / Format
key Your site's domain or the domain that requested this integration. REQUIRED google.com
secret Your user's current secret created during the authentication process. REQUIRED char(128)
phone 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. REQUIRED 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 RECCOMENDED 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

Result

Note: Only JSON responses are available from this API and this API should ONLY be called server side for security reasons.
Parameter Description Example Value / 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 (object) 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.
Key Expected Values Description
risk_score Float 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".
valid_billing_address Boolean Physical address validation and reputation analysis.
valid_shipping_address Boolean Same as above.
valid_billing_email Boolean Light abusive check and reputation analysis for the email address. It is recommended to use our dedicated Email Validation API for deeper analysis.
valid_shipping_email Boolean Same as above.
leaked_billing_email Boolean Indicates if the email address has recently been exposed or compromised in a database breach.
leaked_shipping_email Boolean Same as above.
leaked_user_data Boolean Indicates if the user's data (including phone & address) have recently been exposed or compromised in a database breach.
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", "VOIP", "Satellite", "Premium Rate", "Pager".
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.
bin_country String Country associated with the credit card BIN.
risky_username Boolean Username frequently associated with fraudulent behavior.
is_prepaid_card Boolean Status of the credit card as prepaid.
fraudulent_behavior Boolean Indicates high risk behavior patterns and a high chance of fraud.
phone_name_identity_match String 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.
phone_email_identity_match String 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.
phone_address_identity_match String 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.
email_name_identity_match String 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.
name_address_identity_match String 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.
address_email_identity_match String 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.
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