Postback API & Conversion Notifications Documentation for Proxy Detection

IPQS Postback API allows you to alter previous Proxy Detection API requests to our API based on new or additional data for the purposes of receiving a new fraud score. This API also supports conversion tracking and allows for the conversion status to be updated.

Request Formatting

You may want to update aspects of a proxy request after it happens, such as confirming the conversion date and conversion status. This API allows you to update your request. Requests via this API can be made via POST or GET. For the purposes of our documentation we'll demonstrate GET requests. Parameters passed to the API wrapped as an update[] array will update the original request. Parameters outside of the update[] array will be used to look up the request. Custom tracking variables passed with your initial request must be listed on your account's custom tracking variables in order for the postback update to be successful.

Ideally all postback requests will be submitted using the original "request_id". This is a system unique ID that represents a single call to the API. However we realize that not every caller will be able to store the ID for each request. As a result, the API allows for custom variables to be used instead. Below is your base postback URL (Note this includes your API key. Please keep your API key secret):

Example Lookup by Request ID

Here's how we can lookup a "request_id" of DWwJXYh to retrieve the original API response.

Example Request ID Usage

Let's say we had a "request_id" of DWwJXYh and wanted to update the "transactionID" associated with that request to be 100. Here's how we'd do that:

Example Custom Variable Usage

Let's say we didn't have the "request_id" of the request, but we knew that the request had a "transactionID" of 99 during the original API request. Here's how we can update it (Note: "type" is required, please see table below for acceptable values):

Example Conversion Status Update

Let's say we want to report a converted click along with the conversion date (Y-m-d or Y-m-d H:i:s) and we knew that the request had a "request_id" of "0v1EAC". Here's how we'd update it (Note: type is required, see the table below for acceptable values):

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
ConversionStatus	Boolean, string true or string false	Allows you to flag a request as having lead to a conversion.	update[ConversionStatus]=true
ConversionDate	Date formatted Y-m-d or Y-m-d H:i:s	Allows you to set a date the request was made a conversion.	update[ConversionDate]=2017-01-01
ClickDate	Date formatted Y-m-d or Y-m-d H:i:s	Allows you to alter the first seen date on a device.	update[ClickDate]=2017-01-01
user_agent	String	Updates the user agent string.	update[user_agent]=Lynx/2.8.7dev.9%20libwww-FM/2.14
language	String	Updates the user's browser chosen language.	update[language]=en-US
request_id	String	A unique ID is provided for each request. This can be used to lookup past results.	request_id=DWwJXYh
type	String ("proxy", "email", "devicetracker", or "mobiletracker")	Required for request lookups when you don't provide a "request_id". Fetches a request of this type.	type=proxy
newest	Boolean (true/false)	Defaults to false. When true chooses the most recent request if there is more than one request with your specified parameters.	newest=true
Your custom variables (as defined in account settings):
Please login to display your custom variables for this API.

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

// The original request ID.
$request = 'DWwJ';
	
// New userID
$userID = '1234';

// Base URL
$url = 'https://www.ipqualityscore.com/api/json/postback/%s?%s';
	
// Parameters
$parameters = array(
	'userID' => $userID,
	'request_id' => $request
);

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

# THIS SHOULD NEVER BE USED IN PRODUCTION AS IS!

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

from http.server import BaseHTTPRequestHandler, HTTPServer
import json
import requests

hostName = "localhost"
serverPort = 8080

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

        return (json.loads(x.text))



class MyServer(BaseHTTPRequestHandler):
    """This is an example basic web server. we limited it to handle "/" path only."""

    def do_GET(self):
        if self.path == "/":
            ipqs = IPQS()
            print(ipqs.proxy_vpn_api_postback("request_id_here"))
            self.send_response(200)
            self.send_header("Content-type", "text/html")
            self.end_headers()

if __name__ == "__main__":        
    webServer = HTTPServer((hostName, serverPort), MyServer)
    print("Server started http://%s:%s" % (hostName, serverPort))

    try:
        webServer.serve_forever()
    except KeyboardInterrupt:
        pass

    webServer.server_close()
    print("Server stopped.")