Postback API & Conversion Notifications

About

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

Request Formatting

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

It's important to note that all postback requests should be submitted using the original request_id. This unique ID, which represents a single call to the API, is a key element. We understand that not every caller will be able to store the ID for each request, so the API allows for custom variables to be used instead. Below is your base postback URL (Note this includes your API key. Remember, it's crucial to keep your API key secret):

https://www.ipqualityscore.com/api/json/postback/YOUR_API_KEY_HERE

Example Requests

Example Lookup by Request ID

Replace YOUR_REQUEST_ID with the specific request ID to look up.

https://www.ipqualityscore.com/api/json/postback/YOUR_API_KEY_HERE?request_id=DWwJXYh

Example Custom Variable Usage

Suppose you don't have the request_id of the request but know that the request had a transactionID of 99 during the original API request. In that case, you can update the transactionID of that request with the update[] variable.

Note

The type variable is required. See the table below for acceptable values.

https://www.ipqualityscore.com/api/json/postback/YOUR_API_KEY_HERE?transactionID=99&type=proxy&update[transactionID]=100

Example Conversion Status Update

Suppose you want to report a converted click along with the conversion date, and you know the request had a request_id of 0v1EAC. You can update it with the update[] variable.

Note

The type variable is required. See the table below for acceptable values. The ConversionDate variable requires a format of YYYY-MM-DD or YYYY-MM-DD HH:MM:SS.

https://www.ipqualityscore.com/api/json/postback/YOUR_API_KEY_HERE?request_id=0v1EAC&type=proxy&update[ConversionStatus]=true&update[ConversionDate]=2017-10-21 17:16:18

Request Parameters

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

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

Ready to eliminate fraud?

Start fighting fraud now with 1,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