Postback & Conversion Notifications

About

The IPQS Postback API allows you to alter previous Device Fingerprint 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 URLs

You can make requests to this API via POST or GET. Parameters passed to the API wrapped as an update[] array will update the original request. The API will use any parameters outside of the update[] array to look up the request.

While we recommend using the original request_id for all postback requests, we understand that not every caller can store the ID for each request. As a result, the API allows you to use custom variables instead. For the postback update to succeed, you must establish any custom tracking variables in your account settings before passing them with your initial request.

Below is the base postback URL:

JSON

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

XML

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

Retrieve Data with the Postback API

Suppose you are storing limited data upon the initial check with Startup.AfterResult(), such as the request_id, or would like to re-score a user based on changes you have made to your Custom Scoring Weights. In that case, you can retrieve updated data using the following example.

Replace YOUR_REQUEST_ID with the request_id of the request to retrieve:

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

Alternatively, suppose you didn't know the request_id and did not capture any data with Startup.AfterResult(), but you knew that the request used Startup.Store() to associate the lookup with userID = 99. You can retrieve this data by setting type to the correct tool and appending the userID. This approach supports any variables on your account's Custom Tracking Variables. It will always return the most recent request data that matches the search parameters.

https://www.ipqualityscore.com/api/json/postback/YOUR_API_KEY_HERE?type=devicetracker&userID=99

Using the Startup.AfterResult() format before including the Device Fingerprinting script tag on your site will result in errors and failure of your function to fire. You can call Startup.AfterResult() multiple times while passing several different functions to it. Our library will execute each of them in the order passed.

Postback API requests do not consume an additional credit.

The result variable is an array. The keys and expected values are listed below.

Example Requests

Using the request_id to update the transactionID

Assume a request had a request_id of DWwJ and you wanted to update the transactionID associated with that request to be 100. You would make the following request to the API:

https://www.ipqualityscore.com/api/json/postback/YOUR_API_KEY_HERE?request_id=DWwJ&update[transactionID]=100

Using custom variables to update the transactionID

Assume you wanted to update the transactionID associated with a request to be 100, but you don't know the request_id of that request. You can instead look up the request using a custom variable.

Note

When using custom variables, the type variable is required. See the additional request parameters table below for accepted values.

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

Additional Request Parameters

Parameter Name	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 yyyy-mm-dd or yyyy-mm-dd hh-mm-ss	update[ConversionDate]=2017-01-01
ClickDate	Allows you to alter the first seen date on a device.	Date formatted yyyy-mm-dd or yyyy-mm-dd hh-mm-ss	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 for lookups.	String	request_id=DWwJ
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=devicetracker
tracker_id	This is an optional parameter used to narrow the scope of a variable lookup for a device tracker postback.	Integer (number associated with your tracker in the IPQS device tracker management screen.)	tracker_id=233
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  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.api_postback("request_id_here"))
            self.send_response(200)
            self.send_header("Content-type", "text/html")
            self.end_headers()
            self.wfile.write(bytes("<body>", "utf-8"))

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