Device Fingerprint API Documentation - Getting Started


IPQualityScore's Device Fingerprint Technology allows you to further analyze your users, transactions, ad traffic, and similar data to produce highly accurate Fraud Scores. Multi-layered AI & machine learning algorithms analyze user behavior and intent against millions of patterns to accurately identify high risk activity. Over hundreds of data points are scored to produce a confident result for fraud prevention.


Device Fingerprinting Use Cases
  • Low Quality Users - Identify duplicate user accounts, bogus user information, and fake registrations. Automatically prevent low quality users from hurting your ROI.
  • Click Fraud & Invalid Clicks - Solve click fraud quality issues with real-time click filtering and ensure only high quality clicks.
  • Chargebacks & Payment Fraud - Prevent chargebacks, high risk transactions, and all types of payment fraud.
  • Account Takeover - Monitor accounts for unusual behavior and session hijacking attempts.
  • Bot Detection - Filter non-human traffic in real-time with IPQS bot detection tools.
  • High Risk Behavior - Analyze user behavior against millions of high risk patterns that indicate a user's intent to engage in fraudulent activity.

Getting Started

After creating a Device Fingerprint Tracker you will be presented with a script to include on your website. We recommend placing this script on a funnel page or through a critical flow of your website such as the registration, login, or checkout/payment page. It is also useful at filtering impressions, clicks, redirects, and similar behavior. You may create unique trackers for different pages or sites.

General Usage

It is recommended to associate a request with an identifying piece of information (such as a "userID", "clickID", "transactionID", etc.). Any Custom Tracking Variables established in your account settings can be passed with each device fingerprinting request. This allows our reporting tools to filter by specific users, products, campaigns, transactions, etc. so that you can easily identify fraudulent activity. Simply pass your value(s) to our script as seen below to take advantage of this feature.

General Notes:

  • Note: Always place the variable storage code after the initial Device Fingerprint JavaScript tag. Additionally, all tracking variables passed through the device tracker must be established in your account settings, on the Custom Tracking Variables tab.

Fetching Results

Our system allows you to execute a function after results are finished loading. You can use this for a variety of reasons. The most common include:

  • Recording the device ID for confirming results (see documentation on our API confirmation callback below).
  • Appending the device ID to a form (so you can only allow purchases or completions from devices with clean fraud scores).
  • For performing additional processing or business logic in conjunction with other fraud prevention.
  • For redirecting bots and real users to different versions of your site.

You can specify a function to be executed after our API returns its result by adding something like this after the script tag provided on the tracker page.

General Notes:

  • Note: Using the Startup.AfterResult() format before including the Device Fingerprinting script tag on your site will result in errors and/or failure of your function to fire.
  • You can call Startup.AfterResult() multiple times while passing it several different functions. Our library will execute each of them in the order passed.
  • The result variable is an array. The keys and expected values are listed below.

Expected Result Values
Key Expected Values Description
message string A string describing the output in human terms. Generally this will only have a non-empty value in the case of an error.
success boolean Status of the request.
device_id SHA256 / string A hash of the user's device based on the data we received. This can be used for tracking purposes or passed to our callback for confirmation.
guid SHA256 / string Sticky tracking ID that will stay with the user as they change their IP address, browser, etc. This is the most useful parameter for tracking duplicate accounts. Some "guid" values may represent common default configurations which could correspond to multiple users, so use in conjunction with "guid_confidence".
guid_confidence int (0 - 100) Accuracy of the "guid" match which associates a profile with duplicate users. 0 = not likely, 100 = very likely. A result of 100 is a guaranteed match. Confidence levels below 100 use an intelligent "best guess" approach. Some "guid" results may overlap users, such as a device with factory settings for popular devices.
fraud_chance int (0 - 100) How likely this device is to commit fraud or engage in abusive behavior. 0 = not likely, 100 = very likely. 25 is the median result. Fraud Scores >= 75 are suspicious but not necessarily fraudulent. We recommend flagging or blocking traffic with Fraud Scores >= 85, but you may find it beneficial to use a higher or lower threshold.
proxy boolean Returns true if the lookup is on a Proxy, VPN, or Tor connection.
recent_abuse This value will indicate if there has been any recently verified abuse across our network for this user. Abuse could be a confirmed chargeback, compromised device, fake app install, or similar malicious behavior within the past few days. boolean
country string Two letter country code of the IP address, example: "US".
unique boolean Returns false if this device ID has been seen on multiple IP addresses. Returns true if we haven't seen this ID on multiple IPs.
request_id string A unique identifier for this request that can be used to lookup the request details, interact with our API reports, or send a postback conversion notice.
fast_processing boolean If this request is waiting for a callback or passing tracking variables then fast_processing will be false. Requests process faster without this data.
time int Unix timestamp of request

Catching Failures

You can specify a function to be executed after our API fails to return its results correctly. This could be a result of them blocking some of our tracking or disabling third party scripts.

General Notes:

  • Note: Using the code above before including the script tag on your site will result in errors and/or failure of your function to fire.
  • You can call AfterResult() multiple times and pass it several different functions. Our library will execute each of them in the order passed.

Raw Result Example

Device Fingerprint on Form Triggers

You can optionally process the Device Fingerprint service to collect additional details after the user has performed an action, such as after the user has submitted an order form. Our system allows you to provide an element to bind to as part of an "onclick" trigger. When the user clicks that element, our code will execute and gather the form elements you've specified to perform our Fraud Analysis.

The trigger will override the default action of the element's onclick function, perform our Fraud Analysis and Device Fingerprinting service, and then execute the original action of the element. For example, if you bind the trigger to a form's submit button, our Device Fingerprint script will run first, then it will append the results of the Fraud Detection to your form and submit the form to your server. If you would like to prevent submitting the form right away, then you can use the Startup.AfterResult() function detailed above. If you do choose to use Startup.AfterResult() function, then our Device Tracker will not append the results of the fraud check to your form. The console log will report errors if the service is unable to bind to your supplied trigger.

If you prefer to execute code right before our API is called during a trigger event, you can optionally supply a callback function as the second parameter on Startup.Trigger(). The event object will be passed so you can optionally utilize preventDefault() or call any other function as needed.


Device Fingerprints with Order Forms

The form trigger framework allows you to specify additional fields for order submission and payment processing. These additional fields allow us to better track your users provide better fraud analysis to prevent transaction fraud. Using this feature requires that you use the Startup.Trigger() function as shown above. Without using this function, JavaScript will not properly append data to each request. Accepted fields and values are listed in the table below. If we are unable to locate a specified field, it will be reported in the console logs.

Accepted Order & Transaction Parameters (Optional)

Below is a list of optionally accepted parameters for order & transaction support, a brief description and a listing of their required formatting. All fields are optional, please pass as much data as possible to enhance our fraud scoring engines.

Key Expected Values Description
billing_first_name String The customer's billing first name.
billing_last_name String The customer's billing last name.
billing_company String The customer's billing company.
billing_country String The customer's billing country name or billing country ISO-Alpha2. (EG: United States or US)
billing_address_1 String The customer's billing street address part 1.
billing_address_2 String The customer's billing street address part 2.
billing_city String The customer's billing city.
billing_region String The customer's billing region or state.
billing_postcode String / Number The customer's billing postcode or zipcode.
billing_email String The customer's billing email address.
billing_phone Number The customer's billing 11 to 14 digit phone number. (If less than 10 digits provided, the country code will be guessed by our AI.)
shipping_first_name String The customer's shipping first name.
shipping_last_name String The customer's shipping last name.
shipping_company String The customer's shipping company.
shipping_country String The customer's shipping country name or shipping country ISO-Alpha2. (EG: United States or US)
shipping_address_1 String The customer's shipping street address part 1.
shipping_address_2 String The customer's shipping street address part 2.
shipping_city String The customer's shipping city.
shipping_region String The customer's shipping region or state.
shipping_postcode String / Number The customer's shipping postcode or zipcode.
shipping_email String The customer's shipping email address.
shipping_phone Number The customer's shipping 11 to 14 digit phone number. (If less than 10 digits provided, the country code will be guessed by our AI.)
username String The customer's username.
credit_card_bin Number First six digits of the credit or debit card, referred to ask the Bank Identification Number.
credit_card_hash SHA256 / string For security reasons and following industry best practices, a SHA256 hash of the credit card number is accepted to check against blacklisted cards.
credit_card_expiration_month Number Two letter format of the credit card's expiration month. For example, May would be "05".
credit_card_expiration_year Number Two letter format of the credit card's expiration year. For example, 2022 would be "22".
order_amount Number Total balance of the entire order without currency symbols.
order_quantity Number Quantity of items for this order.
recurring boolean Is this a recurring order that automatically rebills?
recurring_times Number If this is a recurring order, then how many times has this recurring order rebilled? For example, if this is the third time the user is being billed, please enter this value as "3". If this is the initial recurring order, please leave the value as blank or enter "1".