Fraud Reporting API Documentation

IPQualityScore allows you to report fraudulent IP addresses, email addresses, phone numbers, transactions, and similar user data through our Fraud Fusion™ program. Data passed through this API endpoint trains your account's machine learning algorithms that identify high risk behavior among your users, clicks, and transactions. Fraud reports are used by our machine learning artificial intelligence engines to make better decisions on risk analysis for future scoring. We recommend using this fraud reporting API to submit all of your existing bad data, such as abusive users and fraudulent ecommerce payments.

Blacklist Data Sharing

Please refer to our Terms of Service on how this data is used across the IPQS network to improve scoring for all IPQS clients. All data is anonymized and stored using secure protocols.

Request URLs

The URLs below can be used to fetch the result using cURL or another utility in most languages. Please see the usage example at the bottom of the page.

JSON:

XML:

JSON Example Requests

The URL below is an example of how to report an IP address.

The URL below is an example of how to report an email address.

The URL below is an example of how to report a previous request.

The URL below is an example of how to report a phone number.

JSON Success Response Example

{
	"success":true,
	"message":"Success",
	"request_id":"3ift1wF"
}

NOTE: For a description of each field listed above please consult the response documentation below.

XML Success Response Example

<?xml version="1.0" encoding="UTF-8"?>
<result>
	 <request_id>0w8WYS</request_id>        
	 <message>Success</message>
	 <success>true</success>
</result>

NOTE: For a description of each field listed above please consult the response documentation below.

JSON Error Response Examples

Example errors that you may encounter when accessing our API due to an exhausted credit balance or an invalid IP address.

{
	"success":false,
	"message":"You have insufficient credits to make this query. Please contact IPQualityScore support if this error persists.",
	"request_id":"4OTORR352FU0p"
}

{
	"success":false,
	"message":"Information reported already exists in our system.",
	"request_id":"4OTORR4EWpl0m"
}

Request Parameters

Any of the parameters below may be used to report a user for fraudulent activity. At least one of these parameters is required. Request ID is preferred for the best data collection and machine learning results.

Field	Description	Possible Values
ip	The IPv4 or IPv6 address you wish to report. (optional, one required)	IPv4/IPv6 in standard dot/colon notation
email	The email address you wish to report. (optional, one required)	Email Address (string)
request_id	The Request ID you wish to report. (optional, one required)	string
phone	The 9 to 20 digit phone number you wish to report. Must include country field below.(optional, one required, required with country below)	telephone number (number)
country	The 2 letter country code (preferred method) or full properly formatted name (capitalization and spacing required) of the phone number you wish to report. Must include phone field above.(optional, one required, required with phone above)	country code (string)

Additional Request Parameters

The request parameters below can be included optionally in addition to any of the above required parameters. These variables can contain user, lead, or transaction details.

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.
cvv_code	Number	One letter Card Verification Value (CVV2) response code provided by the credit card processor or bank.
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".

Response Field Definitions

The response values will confirm successful receipt of the reported data.

Field	Description	Possible Values
request_id	A unique identifier for this request that can be used to lookup the request details or send a postback conversion notice.	string
message	A generic status message, either success or some form of an error notice.	string
success	Was the request successful?	boolean

// Your API Key.
$key = 'YOUR_API_KEY_HERE';

// Create parameters array.
$parameters = array(
	'ip' => '8.8.8.8', // optional
	'email' => 'noreply@ipqualityscore.com', // optional
	'request_id' => '423tv324fd', //optional
	'phone' => '8007132618', //optional - must include with country
	'country' => 'US' //optional - must include with phone
);

// Format Parameters
$formatted_parameters = http_build_query($parameters);

// Create API URL
$url = sprintf('https://www.ipqualityscore.com/api/json/report/%s?%s',
	$key,
	$formatted_parameters
);

// Fetch The Result
$timeout = 5;

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, $timeout);

$json = curl_exec($curl);
curl_close($curl);

// Decode the result into an array.
$result = json_decode($json, true);

// Check to see if our query was successful.
if(isset($result['success']) && $result['success'] === true){
	// Congratulations your fraud report was successful.
}

import json
import requests

# You may need to install Requests pip
# python -m pip install requests

class IPQS:
    key = 'YOUR_API_KEY_HERE'
    def fraud_reporting_api(self, vars: dict) -> dict:
        url = 'https://www.ipqualityscore.com/api/json/report/%s' %(self.key)
        x = requests.get(url, params = vars)
        return (json.loads(x.text))

if __name__ == "__main__":

    #custom feilds
    additional_params = {
        'ip' : '8.8.8.8', # optional
        'email' : 'noreply@ipqualityscore.com', # optional
        'request_id' : '423tv324fd', # optional
        'phone' : '8007132618', # optional - must include with country
        'country' : 'US' # optional - must include with phone
    }

    print((IPQS()).fraud_reporting_api(additional_params))