Device Fingerprint API Documentation

Device Fingerprinting For Fraud Prevention & User Validation

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 API

Track user accounts with a unique Device ID to detect duplicate accounts and similar risky behavior. Cross device tracking using our device fingerprinting API also detects device spoofing, emulators, bots, location spoofing, GPS tampering, and similar patterns of malicious abuse. Use the API docs below to quickly setup the service on your website or app.

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 ecommerce 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 to analyze behavior. 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 actions. 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.

<script type="text/javascript">
	// tell IPQ we have specific instructions for it.
	var IPQ = {
		Callback: function(){
			Startup.Store('userID', '1234'); // Store the variable userID with the value 1234
			Startup.Store('transactionID', '1234');
			Startup.Init(); // Start the fraud tracker.
		}
	};
</script>

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 Device Fingerprint API 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.

<script type="text/javascript">
	var IPQ = {
		Callback: function(){
			Startup.AfterResult(function(result){
				// Your code here.
			});
			
			Startup.Init(); // Start the fraud tracker.
		}
	};
</script>

Retrieve Data With the Postback API

If you are storing limited data upon the initial check with Startup.AfterResult(), such as the "request_id", or would like to rescore a user based on changes you have made to your Custom Scoring Weights, then you can retrieve updated data using the following example:

Let's say we didn't have the "request_id" and did not capture any data with Startup.AfterResult(), but we knew that the request used Startup.Store() to associate the lookup with "userID" = 99. The data can retrieved by setting "type" to the correct tool and appending the "userID". This approach supports any variables on your account's Custom Tracking Variables and will always return the most recent request data that matches the search parameters.

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.
Postback API requests do not consume an additional credit.

React Device Fingerprinting

Easily deploy our React Device Fingerprinting SDK using our NPM package. If you are not using react, then please continue using the documentation on this page to integrate JavaScript device fingerprinting. Mobile device fingerprint SDKs for Android and iOS are also available upon request.

Expected Result Values

Key	Expected Values	Description
success	boolean	Status of the request.
device_id	SHA256 / string	The Device ID is generated as a hash from the user's device hardware and personal settings. This value can be used for tracking users, detecting duplicate accounts, or passed to our callback endpoint for confirmation.
guid	SHA256 / string	Hardware tracking ID which uses a different algorithm for calculating a hash of the user's device. This value can overlap with other devices that share the same hardware configuration. Please use in conjunction with "guid_confidence".
guid_confidence	int (0 - 100)	Accuracy of the "guid" match which associates a GUID hardware profile with other users, where 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 >= 85 are suspicious, but not necessarily fraudulent. We recommend flagging or blocking traffic with Fraud Scores >= 90, but you may find it beneficial to use a higher or lower threshold.
is_crawler	boolean	Is this device associated with being a confirmed crawler from a mainstream search engine such as Googlebot, Bingbot, Yandex, etc.
connection_type	string	Classification of the IP address connection type as "Residential", "Corporate", "Education", "Mobile", or "Data Center".
proxy	boolean	Returns true if the lookup is on a Proxy, VPN, or Tor connection.
vpn	boolean	Is this IP suspected of being a VPN connection? (proxy will always be true if this is true)
tor	boolean	Is this IP suspected of being a Tor connection? (proxy will always be true if this is true)
active_vpn	Premium Account Feature - Identifies active VPN connections used by popular VPN services and private VPN servers.	boolean
active_tor	Premium Account Feature - Identifies active TOR exits on the TOR network.	boolean
recent_abuse	boolean	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.
bot_status	boolean	Premium Account Feature - Indicates if this device is a bot, spoofed device, or non-human request. Provides stronger confidence in decision making.
reasons	array[string]	Premium Account Feature - Fraud Score Insights explain how this device's Fraud Score was calculated and provides further detail into enhanced Fraud Scores and penalties. This data point is only available via the postback API so real-time users cannot reverse engineer why they were penalized.
ssl_fingerprint	string	Premium Account Feature - SSL fingerprint contains a sha256 of the SSL/TLS cyphers this device supports. Useful for detecting small changes in device fingerprints. This data point is only available via the postback API so real-time users cannot reverse engineer why they were penalized.
device_timezone	boolean	Premium Account Feature - Time zone pulled directly from the user's device. This value may still look accurate and aligned to the user's IP location for high risk users, however we do detect location spoofing through other device signals.
high_risk_device	boolean	Premium Account Feature - Indicates devices with a high confidence of fraudulent activity including emulators, virtual devices, location spoofing, and automated behavior.
ISP	string	Internet Service Provider of the IP address. If unavailable, then "N/A".
country	string	Two letter country code of the IP address, example: "US".
city	string	City of IP address if available or "N/A" if unknown.
region	string	Region or state of IP address if available or "N/A" if unknown.
timezone	string	Time zone of IP address if available or "N/A" if unknown.
mobile	boolean	Is this a mobile device?
operating_system	string	Operating system name and version or "N/A" if unknown.
browser	string	Browser name and version or "N/A" if unknown.
brand	string	Brand name of the device or "N/A" if unknown.
model	string	Model name of the device or "N/A" if unknown.
ip_address	string	The IP Address associated with the device in IPv4 or IPv6 format.
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.
canvas_hash	SHA256 / string	A hash of the user's Canvas profile, calculated by the graphics card and other device hardware. This value is often not unique, so should not be used to identify a specific user.
webgl_hash	SHA256 / string	A hash of the user's WebGL profile, calculated by the graphics card and other device hardware. This value is often not unique, so should not be used to identify a specific user.
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.
click_date	Date Time	Time of this request. (Premium feature)
first_seen	Date Time	Time of the first request. (Premium feature)
last_seen	Date Time	Time of the most recent request. (Premium feature)

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.

<script type="text/javascript">
	var IPQ = {
		Callback: function(){
			Startup.AfterFailure(function(result){
				// Your code here.
			});

			Startup.Init(); // Start the fraud tracker.
		}
	};
</script>

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_id":"97bf540d96b26c3afc612df213ced691510ad714a4563a2201b65442dfa610e5",
	"unique":false,
	"fraud_chance":71,
	"is_crawler":false,
	"proxy":false,
	"vpn":false,
	"tor":false,
	"connection_type":"Residential",
	"ISP":"Mediacom Cable",
	"timezone":"America Matamoros",
	"recent_abuse":false,
	"bot_status":false,
	"country":"US",
	"city":"Houston",
	"region":"Texas",
	"operating_system":Mac 10.6,
	"browser":Chrome 128.0,
	"model":iPad,
	"brand":Apple,
	"mobile":false,
	"fast_processing":false,
	"guid":"7c02c9cb41624a34d4b1d0fddaa34198899865464f7d3a9e997486f311860a4e",
	"guid_confidence":"100",
	"canvas_hash":"757a7b7455a2e163c9ca5a8bed646d87017d24a65e3531ef6910b7638d354fc6",
	"webgl_hash":"034c532c2df0b5aedc169801075f56d36d15e872cc36d8b6df9b14bc0bf024ce",
	"ssl_fingerprint":"l7koJkPziVVkZThY75b3OXIhT4qpzlcfs696wiQhsdQx1o2Sbqkr9l4t2cdrYpUh",
	"time":1493800847,
	"device_timezone":"America/New_York",
	"high_risk_device":false,
	"active_vpn":false,
	"active_tor":false,
	"ip_address":"8.8.8.8",
	"request_id":"0v1Vbz"
}

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 or purchase form. Our system allows you to provide an element to bind to as part of an "onclick" or "onsubmit" trigger. When the user clicks or submits that element, the Device Fingerprint code will execute and gather the form elements you've specified to perform fraud analysis.

<form method="POST" action="/" id="testform" >
	<button type="submit" >Submit</button>
</form>
<script type="text/javascript">
	var IPQ = {
		Callback: function(){
			Startup.FormFieldPrepend  = 'ipqs_';
			Startup.Trigger('#testform'); // or Startup.Trigger('.element') or Startup.Trigger('button');
			Startup.Init(); // Tell device tracker to start.
		}
	};
</script>

The trigger will override the default action of the element's "onclick" or "onsubmit" function, perform IPQS 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 our fraud scoring to your form, and submit the form to your server. Setting "Startup.FormFieldPrepend" will prepend a title to all appended form variables as shown in the example above.

If you would like to prevent submitting the form right away, then you can use the Startup.AfterResult() function detailed above. When using the Startup.AfterResult() function, the Device Fingerprint will not append the results 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.

<script type="text/javascript">
	var IPQ = {
		Callback: function(){
			Startup.Trigger("#element", function(event){
				event.preventDefault();
				Startup.Store('OrderID', 34522);
			});
			
			Startup.Init(); // Tell device tracker to start.
		}
	};
</script>

Device Fingerprinting with Transaction Data

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.

<script type="text/javascript">
	var IPQ = {
		Callback: function(){
			Startup.Field('billing_country', '#country'); // or Startup.Field('billing_city', '.city'); EG: Startup.Field('IPQualityScore_Field_Name', 'htmlelement');
			Startup.Init(); // Tell device tracker to start.
		}
	};
</script>

Additional Methods to Pass Data

Instead of binding to a form, it is possible to delay the initial fingerprint processing by using Startup.Pause() and later Startup.Resume(). This pre-loads the necessarily JavaScript to fingerprint the user, but waits until Startup.Resume() has been called to process the request. Therefor, user inputted data, not available on the initial page load, can be attached to the initial request as in the example below:

var IPQ = {
	Callback: function(){
		Startup.Pause(); // prevent fingerprint script from loading on page load
		Startup.Init(); // Startup the background processor.
		Startup.Store('OrderID', '34522'); // any custom tracking variable
		Startup.FieldStore('billing_email', 'USEREMAILVALUE'); // any transaction variable
	  
		Startup.AfterResult(function(result){
			// retrieve data here or use the postback API to lookup by Startup.Store() value.
		});

		Startup.Resume(); // resumes fingerprint request
	}
};

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 and should be passed with Startup.FieldStore(). Please note, it is recommended to use our dedicated Transaction Scoring API for more accurate analysis on transaction & user data.

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.
password_hash	SHA256 / string	For security reasons and following industry best practices, a SHA256 hash of the user's password for better user analysis.
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".
avs_code	Number	One letter Address Verification Service (AVS) response code provided by the credit card processor or bank.
cvv_code	Number	One letter Card Verification Value (CVV2) response code provided by the credit card processor or bank.
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".

What is a Device Fingerprinting API?

Device Fingerprinting APIs profile devices in real-time to calculate a unique device ID and risk profile, based on the behavior and settings of the user's device. IPQS device fingerprinting produces accurate risk scores based on the quality of the user's device and behavior. For example, non-human bot behavior would indicate malicious activity and increase the risk score. Unique device IDs allow a website to accurately identify users with multiple accounts or high risk payments.

When To Use a Device Fingerprinting API?

Using an Device Fingerprint API is a best practice to detect fraud during registration, payment or checkout, and similar user actions. Retrieve a device risk score as well as a device ID that can be used to track the user across your website. Real-time results provided by the device Application Programming Interface (API) can enrich user accounts and payment data.

What is Device Fingerprinting?

Device Fingerprinting is the process of creating a device tracking ID and risk profile based on a user's device behavior and settings. The IPQS device fingerprinting service creates a unique device ID to track users as they interact with your site, and better understand quality based on a user's behavior during login, checkout, account creation, and similar actions.