Custom Integrations - Making IP/Proxy Checks Documentation

This API endpoint allows you to perform Proxy Detection and IP reputation checks on behalf of your users in an almost identical fashion to our standard user API structure.

Calling IP Reputation/Proxy Detection

https://www.ipqualityscore.com/webhooks/ExampleIntegration/json/proxy_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)
ip	The IP you wish to perform a proxy/ip validation check against. REQUIRED	IPv4 or IPv6 address in dot/colon notation.
strictness	How in depth (strict) do you want this query to be? Higher values take longer to process and 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 - 5
user_agent	You can optionally provide us with the user agent string (browser). This allows us to run additional checks to see if the user is a bot or running an invalid browser. This allows us to evaluate the risk of the user as judged in the "fraud_score".	string
user_language	You can optionally provide us with the user's language header. This allows us to evaluate the risk of the user as judged in the "fraud_score".	string
fast	When this parameter is enabled our API will not perform certain forensic checks that take longer to process. Enabling this feature greatly increases the API speed without much impact on accuracy. This option is intended for services that require decision making in a time sensitive manner and can be used for any strictness level.	boolean, string (true or false)
mobile	You can optionally specify that this lookup should be treated as a mobile device. Recommended for mobile lookups that do not have a user agent attached to the request. NOTE: This can cause unexpected and abnormal results if the device is not a mobile device.	boolean, string (true or false)
allow_public_access_points	Bypasses certain checks for IP addresses from education and research institutions, schools, and some corporate connections to better accommodate audiences that frequently use public connections.	boolean, string (true or false)
transaction_strictness	Adjusts the weights for penalties applied due to irregularities and fraudulent patterns detected on order and transaction details that can be optionally provided on each API request. This feature is only beneficial if you are passing order and transaction details. A table is available further down the page with supported transaction variables.	integer, 0 - 2

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
message	Description of the status of this call. May contain errors if errors exist.	text
success	Boolean result of if the request was successful or not.	boolean
proxy	Is this IP address suspected to be a proxy? (SOCKS, Elite, Anonymous, VPN, Tor, etc.)	boolean
host	Hostname of the IP address if one is available.	string
ISP	ISP if one is known. Otherwise "N/A".	string
Organization	Organization if one is known. Can be parent company or sub company of the listed ISP. Otherwise "N/A".	string
ASN	Autonomous System Number if one is known. Otherwise "N/A".	string
country_code	Two character country code of IP address or "N/A" if unknown.	string
city	City of IP address if available or "N/A" if unknown.	string
region	Region (state) of IP address if available or "N/A" if unknown.	string
timezone	Timezone of IP address if available or "N/A" if unknown.	string
latitude	Latitude of IP address if available or "N/A" if unknown.	string
longitude	Longitude of IP address if available or "N/A" if unknown.	string
is_crawler	Is this IP is associated with being a confirmed crawler such as Googlebot, Bingbot, etc based on hostname or IP address verification.	boolean
recent_abuse	This value will indicate if there has been any recently verified abuse across our network for this IP address. Abuse could be a confirmed chargeback, compromised device, fake app install, or similar malicious behavior within the past few days.	boolean
vpn	Is this IP suspected of being a VPN connection? (proxy will always be true if this is true)	boolean
tor	Is this IP suspected of being a Tor connection? (proxy will always be true if this is true)	boolean
mobile	Is this user agent a mobile browser? (will always be false if the user agent is not passed in the API request)	boolean
fraud_score	The overall fraud score of the user based on the IP, user agent, language, and any other optionally passed variables. We recommend that any fraud score equal to or over 75 be treated as a risky user.	float
request_id	A unique identifier for this request that can be used to lookup the request details or send a postback conversion notice.	string
operating_system	Operating system name and version or "N/A" if unknown. Requires the "user_agent" variable in the API Request.	string
browser	Browser name and version or "N/A" if unknown. Requires the "user_agent" variable in the API Request.	string
device_brand	Brand name of the device or "N/A" if unknown. Requires the "user_agent" variable in the API Request.	string
device_model	Model name of the device or "N/A" if unknown. Requires the "user_agent" variable in the API Request.	string
transaction_details	Additional scoring variables for risk analysis are available when transaction data is passed through the API request. These variables are also useful for scoring physical addresses, phone numbers, usernames, transaction info, and similar data passed with the API request. The following transaction variables are returned as booleans, and "null" when the necessary transaction parameters are not passed with the API request. For instance, not passing the "billing_email" will return "valid_billing_email" as null. valid_billing_address valid_shipping_address valid_billing_email valid_shipping_email risky_billing_phone risky_shipping_phone fraudulent_behavior bin_country risky_username valid_billing_phone valid_shipping_phone leaked_billing_email leaked_shipping_email leaked_user_data	object
errors	Array of errors which occurred while attempting to process this request.	array of strings

Order & Transaction Fraud Scoring

Additional user data for orders, transactions, lead generation, and user information can be analyzed to enhance Fraud Scores. The following fields are entirely optional and provide additional data that can be used to detect fraudulent patterns and behavior. Any additional data beyond the IP address greatly improves detecting high risk users.

Risk analysis on transaction data will be displayed in the "transaction_details" object. If only one address is available for the user or transaction, then please enter the address data into the shipping or billing variables, rather than entering the same address in both variables. Passing the email address also contributes to detecting fraudulent users, however only a light abusive check will be performed. Using a full lookup with our Email Verification API will provide greater details and accuracy. Variables listed below that are irrelevant to your requirements can be ignored.

Key	Expected Values	Description
billing_first_name	String	The customer's billing first name.
billing_last_name	String	The customer's billing last name.
billing_company	String	The customer's billing company.
billing_country	String	The customer's billing country name or billing country ISO-Alpha2. (EG: United States or US)
billing_address_1	String	The customer's billing street address part 1.
billing_address_2	String	The customer's billing street address part 2.
billing_city	String	The customer's billing city.
billing_region	String	The customer's billing region or state.
billing_postcode	String / Number	The customer's billing postcode or zipcode.
billing_email	String	The customer's billing email address.
billing_phone	Number	The customer's billing 11 to 14 digit phone number. (If less than 10 digits provided, the country code will be guessed by our AI.)
shipping_first_name	String	The customer's shipping first name.
shipping_last_name	String	The customer's shipping last name.
shipping_company	String	The customer's shipping company.
shipping_country	String	The customer's shipping country name or shipping country ISO-Alpha2. (EG: United States or US)
shipping_address_1	String	The customer's shipping street address part 1.
shipping_address_2	String	The customer's shipping street address part 2.
shipping_city	String	The customer's shipping city.
shipping_region	String	The customer's shipping region or state.
shipping_postcode	String / Number	The customer's shipping postcode or zipcode.
shipping_email	String	The customer's shipping email address.
shipping_phone	Number	The customer's shipping 11 to 14 digit phone number. (If less than 10 digits provided, the country code will be guessed by our AI.)
username	String	The customer's username.
password_hash	SHA256 / string	For security reasons and following industry best practices, a SHA256 hash of the user's password for better user analysis.
credit_card_bin	Number	First six digits of the credit or debit card, referred to ask the Bank Identification Number.
credit_card_hash	SHA256 / string	For security reasons and following industry best practices, a SHA256 hash of the credit card number is accepted to check against blacklisted cards.
credit_card_expiration_month	Number	Two letter format of the credit card's expiration month. For example, May would be "05".
credit_card_expiration_year	Number	Two letter format of the credit card's expiration year. For example, 2022 would be "22".
avs_code	Number	One letter Address Verification Service (AVS) response code provided by the credit card processor or bank. A full list of acceptable response codes can be viewed here.
cvv_code	Number	One letter Card Verification Value (CVV2) response code provided by the credit card processor or bank. A full list of acceptable response codes can be viewed here.
order_amount	Number	Total balance of the entire order without currency symbols.
order_quantity	Number	Quantity of items for this order.
recurring	boolean	Is this a recurring order that automatically rebills?
recurring_times	Number	If this is a recurring order, then how many times has this recurring order rebilled? For example, if this is the third time the user is being billed, please enter this value as "3". If this is the initial recurring order, please leave the value as blank or enter "1".

Example Code


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

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

// The IP we want to check.
$ip = '8.8.8.8';

// Prepare POST fields.
$fields = array(
	'secret' => $secret,
	'key' => $key,
	'ip' => $ip
);
	
// 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 proxy or not.
		if($output['proxy'] === true){
			echo "The IP ".$ip." is a proxy.";
		} else {
			echo "The IP ".$ip." is not a proxy.";
		}
	
	} else {
		echo $output['message'];
	}
} else {
	echo "There appears to be an unforeseen error. Please contact IPQualityScore support if this persists.";
}