Request List API Documentation

IPQS Request List API allows you to retrieve previous Proxy Detection API, Email Validation API and Device Fingerprinting technology requests to our API based on the date they occurred or custom variables.

Request Formatting

You may want to retrieve the results of previous requests to our API in bulk for additional external processing. Requests via this API can be made via POST or GET. For the purposes of our documentation we'll demonstrate GET requests. Custom tracking variables passed with your initial request must be listed on your account's custom tracking variables in order for the request to be successful. All requests to this API must contain a "type" parameter corresponding to the original request's type ("proxy", "email", "devicetracker", or "mobiletracker").

You can request a date range from our API like such:

Example Custom Variable Usage

Let's say we knew that the request had a "transactionID" of 99. Here's how we'd request to see all requests with a transaction ID of 99. (Note: type is required, see the table below for acceptable values):

JSON Success Response Example

NOTE: The structure of each request will vary based on the type specified. For more details about what format to expect for your query type, please refer to: Proxy Detection API, Email Validation API or Device Fingerprinting technology

{
	"success": true,
	"requests": [{
		"ASN": "15169",
		"ISP": "Google",
		"country_code": "US",
		"region": "California",
		"city": "Mountain View",
		"organization": "Google",
		"latitude": 37.41,
		"longitude": -122.08,
		"is_crawler": false,
		"timezone": "America\/Chicago",
		"mobile": false,
		"host": "dns.google",
		"proxy": true,
		"vpn": true,
		"tor": false,
		"recent_abuse": true,
		"bot_status": true,
		"success": true,
		"message": "Success",
		"fraud_score": 100,
		"transaction_details": [],
		"request_id": "4JAer3sX6rH3Xl"
	}],
	"current_page": 1,
	"total_pages": 1,
	"request_count": 1,
	"max_records_per_page": 25,
	"total_records": 1,
	"request_id": "4JAer3sX6rH3bk"
}

Additional Request Options

Due to the nature of platform requirements or frameworks it may be necessary to request IPQS API endpoints without passing the API key in the URL. As an alternative, IPQS allows the API key to be passed via GET, POST, or Headers. These requests use the following endpoints:

JSON:

XML:

Method	Value	Example
GET	key	?key=YOUR_API_KEY_HERE&transactionID=99&type=proxy
POST	key	key=YOUR_API_KEY_HERE&transactionID=99&type=proxy
Header	IPQS-KEY (Additional parameters passed as either GET or POST)	IPQS-KEY: YOUR_API_KEY_HERE

Accepted Parameters

Below is a list of accepted parameters, a brief description and a listing of their required formatting.

Parameter Name	Expected Values	Description	Update Example
type	String ("proxy", "email", "phone", "devicetracker", or "mobiletracker")	Required	type=proxy
page	Integer (1+)	The page number you are requesting. Defaults to 1 if not specified. Used to retrieve more results than the limit provides.	page=2
limit	Integer (1 - 250)	Allows you to specify how many results will be returned with your query up to a maximum of 250. Defaults to 25.	limit=100
start_date	Date formatted Y-m-d or Y-m-d H:i:s	Fetches records newer than or equal to the date specified.	start_date=2020-01-01
stop_date	Date formatted Y-m-d or Y-m-d H:i:s	Fetches records older than or equal to the date specified.	stop_date=2020-01-31
tracker_id	Integer (number associated with your tracker in the IPQS device tracker management screen.)	This is an optional parameter used to narrow the scope of a variable lookup for a device tracker type.	tracker_id=555
device_id	SHA256 / string	This is an optional parameter to search all matching device ID queries with device fingerprinting.	device_id=888
min_fraud_score	Number 0 - 100	This is an optional parameter to limit results to only contain fraud scores greater than or equal to this number.	min_fraud_score=45
max_fraud_score	Number 0 - 100	This is an optional parameter to limit results to only contain fraud scores less than or equal to this number.	max_fraud_score=80
ip_address	string	This is an optional parameter to search all matching IP address queries for "proxy", "devicetracker", and "mobiletracker" types.	ip_address=8.8.8.8
Your custom variables (as defined in account settings):
Please login to display your custom variables for this API.

Response Field Definitions

Below is a list of expected result fields for your query.

Field	Description	Possible Values
success	Was the request successful?	boolean
requests	Array of result objects. (Please refer to: Proxy Detection API, Email Validation API or Device Fingerprinting API)	array of objects
current_page	Which page of results was returned by this query.	integer
total_pages	Total number of results pages this query produced.	integer
request_count	How many results are on this page.	integer
max_results_per_page	How many results this response should contain.	integer
total_requests	How many results exist in total for this query.	integer
request_id	A unique identifier for this request.	String

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

// The original request type
// possible values: "proxy", "devicetracker", "email", or "mobiletracker"
$type = 'proxy';
	
// The date we're looking for records from.
$start_date = '2020-01-01';

// Optional IP address
$ip_address = '8.8.8.8';

// Optional Device ID (device fingerprinting only)
$device_id = 'T3G4fy07D82564i8hYNo2t83TpC84y5d1M3OKN4502U6ObDk8U3987KlRxn75prz'

// Base URL
$url = 'https://www.ipqualityscore.com/api/json/requests/%s/list?%s';
	
// Parameters
$parameters = array(
	'type' => $type,
	'start_date' => $start_date,
	'device_id' => $device_id,
	'ip_address' => $ip_address
);

// Build our query.
$query = http_build_query($parameters);

// Finish assembling the URL and make the request.
$json = file_get_contents(sprintf($url, $key, $query));
	
// Exit and print the response.
exit(print_r(json_decode($json, true)));

import json
import requests

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

class IPQS:
    key = "YOUR_API_KEY_HERE"
    def request_list_api(self, vars: dict = {}) -> dict:
        url = 'https://www.ipqualityscore.com/api/json/requests/%s/list' % (self.key)
        x = requests.get(url, params = vars)

        return (json.loads(x.text))

if __name__ == "__main__":

    # The original request type
    # possible values: "proxy", "devicetracker", "email", or "mobiletracker"
    type = 'proxy'
        
    # The date we're looking for records from.
    start_date = '2020-01-01'

    # Optional IP address
    ip_address = '8.8.8.8'

    # Optional Device ID (device fingerprinting only)
    device_id = 'T3G4fy07D82564i8hYNo2t83TpC84y5d1M3OKN4502U6ObDk8U3987KlRxn75prz'

    # Base URL
    url = 'https://www.ipqualityscore.com/api/json/requests/%s/list?%s'
        
    # Parameters
    parameters = {
        'type' : type,
        'start_date' : start_date,
        'device_id' : device_id,
        'ip_address' : ip_address
    }

    print((IPQS()).request_list_api(parameters))