<< Back to Categories

Getting Started

About the Fraud Reporting API

IPQS 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, which 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 e-commerce payments.

Refer to our Terms of Service for information 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.

API Request URLs

You can use the following URLs to submit requests to the Fraud Reporting API using cURL or another utility in most languages.

JSON

XML

Required Parameters

Requests to the Fraud Reporting API must include one of the following parameters:

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

Example Requests

Reporting an IP Address

Reporting an Email Address

Reporting a Previous Request

Reporting a Phone Number

Response Examples

Success Responses

This is an example success response in JSON format. Details about each of these variables can be found in Response Parameters.

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

This is an example success response in XML format. Details about each of these variables can be found in Response Parameters.

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

Error Responses

This is an example error response due to insufficient credits.

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

This is an example error response received when the information has already been reported.

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

EXAMPLE CODE

PHP
PYTHON

// 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))

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