Skip to main content
WEBHOOK
event
{
  "event_id": "<string>",
  "timestamp": 123,
  "linked_id": "<string>",
  "environment_id": "<string>",
  "suspect": true,
  "replayed": true,
  "tags": {},
  "url": "<string>",
  "bundle_id": "<string>",
  "package_name": "<string>",
  "ip_address": "<string>",
  "user_agent": "<string>",
  "client_referrer": "<string>",
  "bot_type": "<string>",
  "cloned_app": true,
  "developer_tools": true,
  "emulator": true,
  "factory_reset_timestamp": 123,
  "frida": true,
  "ip_blocklist": {
    "email_spam": true,
    "attack_source": true,
    "tor_node": true
  },
  "ip_info": {},
  "proxy": true,
  "proxy_ml_score": 0.5,
  "incognito": true,
  "jailbroken": true,
  "location_spoofing": true,
  "mitm_attack": true,
  "privacy_settings": true,
  "root_apps": true,
  "rule_action": {
    "ruleset_id": "<string>",
    "rule_id": "<string>",
    "rule_expression": "<string>",
    "request_header_modifications": {
      "remove": [
        "<string>"
      ],
      "set": [
        {
          "name": "<string>",
          "value": "<string>"
        }
      ],
      "append": [
        {
          "name": "<string>",
          "value": "<string>"
        }
      ]
    }
  },
  "simulator": true,
  "suspect_score": 123,
  "tampering": true,
  "tampering_ml_score": 0.5,
  "tampering_details": {
    "anomaly_score": 0.5,
    "anti_detect_browser": true
  },
  "velocity": {},
  "virtual_machine": true,
  "virtual_machine_ml_score": 0.5,
  "vpn": true,
  "vpn_origin_timezone": "<string>",
  "vpn_origin_country": "<string>",
  "vpn_methods": {
    "timezone_mismatch": true,
    "public_vpn": true,
    "auxiliary_mobile": true,
    "os_mismatch": true,
    "relay": true
  },
  "high_activity_device": true,
  "rare_device": true,
  "raw_device_attributes": {
    "font_preferences": {
      "default": 123,
      "serif": 123,
      "sans": 123,
      "mono": 123,
      "apple": 123,
      "min": 123,
      "system": 123
    },
    "emoji": {
      "font": "<string>",
      "width": 123,
      "height": 123,
      "top": 123,
      "bottom": 123,
      "left": 123,
      "right": 123,
      "x": 123,
      "y": 123
    },
    "fonts": [
      "Arial Unicode MS",
      "Gill Sans",
      "Helvetica Neue",
      "Menlo"
    ],
    "device_memory": 8,
    "timezone": "<string>",
    "canvas": {
      "winding": true,
      "geometry": "<string>",
      "text": "<string>"
    },
    "languages": [
      [
        "<string>"
      ]
    ],
    "webgl_extensions": {
      "context_attributes": "<string>",
      "parameters": "<string>",
      "shader_precisions": "<string>",
      "extensions": "<string>",
      "extension_parameters": "<string>",
      "unsupported_extensions": [
        "<string>"
      ]
    },
    "webgl_basics": {
      "version": "<string>",
      "vendor": "<string>",
      "vendor_unmasked": "<string>",
      "renderer": "<string>",
      "renderer_unmasked": "<string>",
      "shading_language_version": "<string>"
    },
    "screen_resolution": [
      123
    ],
    "touch_support": {
      "touch_event": true,
      "touch_start": true,
      "max_touch_points": 123
    },
    "oscpu": "<string>",
    "architecture": 123,
    "cookies_enabled": true,
    "hardware_concurrency": 123,
    "date_time_locale": "<string>",
    "vendor": "<string>",
    "color_depth": 123,
    "platform": "<string>",
    "session_storage": true,
    "local_storage": true,
    "audio": 123,
    "plugins": [
      {
        "name": "<string>",
        "description": "<string>",
        "mimeTypes": [
          {
            "type": "<string>",
            "suffixes": "<string>",
            "description": "<string>"
          }
        ]
      }
    ],
    "indexed_db": true,
    "math": "<string>",
    "device_model": "<string>",
    "device_manufacturer": "<string>",
    "font_hash": "<string>",
    "timezone_offset": "<string>"
  },
  "labels": [
    {
      "label": "<string>",
      "prediction": true,
      "ml_score": 0.5
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.fingerprint.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Add your Secret API Key to the Authorization header using the standard Bearer format: Authorization: Bearer <secret_api_key>

Body

application/json

If configured, a Webhook event will be posted to the provided endpoint. The webhook has the same data as our /v4/events endpoint.

Contains results from Fingerprint Identification and all active Smart Signals.

​
event_id
string
required

Unique identifier of the user's request. The first portion of the event_id is a unix epoch milliseconds timestamp For example: 1758130560902.8tRtrH

​
timestamp
integer<int64>
required

Timestamp of the event with millisecond precision in Unix time.

​
incremental_identification_status
enum<string>

Only included for requests using incremental identification.

  • partially_completed - Indicates this event corresponds to a 'minimal' request. Smart Signals, even if included in your plan, are not computed; hence, their values must be ignored.
  • completed - Indicates this event corresponds to a 'complete' request. Smart Signals, if included in your plan, are computed; hence, their values are valid and relevant.
Available options:
partially_completed,
completed
​
linked_id
string

A customer-provided id that was sent with the request.

​
environment_id
string

Environment Id of the event. For example: ae_47abaca3db2c7c43

​
suspect
boolean

Field is true if you have previously set the suspect flag for this event using the Server API Update event endpoint.

​
sdk
object

Contains information about the SDK used to perform the request.

​
replayed
boolean

true if we determined that this payload was replayed, false otherwise.

​
identification
object
​
supplementary_id_high_recall
object

The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental.

​
tags
object

A customer-provided value or an object that was sent with the identification request or updated later.

​
url
string

Page URL from which the request was sent. For example https://example.com/

​
bundle_id
string

Bundle Id of the iOS application integrated with the Fingerprint SDK for the event. For example: com.foo.app

​
package_name
string

Package name of the Android application integrated with the Fingerprint SDK for the event. For example: com.foo.app

​
ip_address
string

IP address of the requesting browser or bot.

​
user_agent
string

User Agent of the client, for example: Mozilla/5.0 (Windows NT 6.1; Win64; x64) ....

​
client_referrer
string

Client Referrer field corresponds to the document.referrer field gathered during an identification request. The value is an empty string if the user navigated to the page directly (not through a link, but, for example, by using a bookmark) For example: https://example.com/blog/my-article

​
browser_details
object
​
proximity
object

Proximity ID represents a fixed geographical zone in a discrete global grid within which the device is observed.

​
bot
enum<string>

Bot detection result:

  • bad - bad bot detected, such as Selenium, Puppeteer, Playwright, headless browsers, and so on
  • good - good bot detected, such as Google bot, Baidu Spider, AlexaBot and so on
  • not_detected - the visitor is not a bot
Available options:
bad,
good,
not_detected
​
bot_type
string

Additional classification of the bot type if detected.

​
bot_info
object

Extended bot information.

​
cloned_app
boolean

Android specific cloned application detection. There are 2 values:

  • true - Presence of app cloners work detected (e.g. fully cloned application found or launch of it inside of a not main working profile detected).
  • false - No signs of cloned application detected or the client is not Android.
​
developer_tools
boolean

true if the browser has DevTools open (Chrome, Firefox) or the Android/iOS device has Developer Tools enabled, false otherwise.

​
emulator
boolean

Android specific emulator detection. There are 2 values:

  • true - Emulated environment detected (e.g. launch inside of AVD).
  • false - No signs of emulated environment detected or the client is not Android.
​
factory_reset_timestamp
integer<int64>

The time of the most recent factory reset that happened on the mobile device is expressed as Unix epoch time. When a factory reset cannot be detected on the mobile device or when the request is initiated from a browser, this field will correspond to the epoch time (i.e 1 Jan 1970 UTC) as a value of 0. See Factory Reset Detection to learn more about this Smart Signal.

​
frida
boolean

Frida detection for Android and iOS devices. There are 2 values:

  • true - Frida detected
  • false - No signs of Frida or the client is not a mobile device.
​
ip_blocklist
object
​
ip_info
object

Details about the request IP address. Has separate fields for v4 and v6 IP address versions.

​
proxy
boolean

IP address was used by a public proxy provider or belonged to a known recent residential proxy

​
proxy_confidence
enum<string>

Confidence level of the proxy detection. If a proxy is not detected, confidence is "high". If it's detected, can be "low", "medium", or "high".

Available options:
low,
medium,
high
​
proxy_details
object

Proxy detection details (present if proxy is true)

​
proxy_ml_score
number<double>

Machine learning–based proxy score, represented as a floating-point value between 0 and 1 (inclusive), with up to three decimal places of precision. A higher score means a higher confidence in the positive proxy detection result. This Smart Signal is currently in beta and only available to select customers. If you are interested, please contact our support team.

Required range: 0 <= x <= 1
​
incognito
boolean

true if we detected incognito mode used in the browser, false otherwise.

​
jailbroken
boolean

iOS specific jailbreak detection. There are 2 values:

  • true - Jailbreak detected.
  • false - No signs of jailbreak or the client is not iOS.
​
location_spoofing
boolean

Flag indicating whether the request came from a mobile device with location spoofing enabled.

​
mitm_attack
boolean
  • true - When requests made from your users' mobile devices to Fingerprint servers have been intercepted and potentially modified.
  • false - Otherwise or when the request originated from a browser. See MitM Attack Detection to learn more about this Smart Signal.
​
privacy_settings
boolean

true if the request is from a privacy aware browser (e.g. Tor) or from a browser in which fingerprinting is blocked. Otherwise false.

​
root_apps
boolean

Android specific root management apps detection. There are 2 values:

  • true - Root Management Apps detected (e.g. Magisk).
  • false - No Root Management Apps detected or the client isn't Android.
​
rule_action
object

Informs the client that the request should be forwarded to the origin with optional request header modifications.

​
simulator
boolean

iOS specific simulator detection. There are 2 values:

  • true - Simulator environment detected.
  • false - No signs of simulator or the client is not iOS.
​
suspect_score
integer

Suspect Score is an easy way to integrate Smart Signals into your fraud protection work flow. It is a weighted representation of all Smart Signals present in the payload that helps identify suspicious activity. The value range is [0; S] where S is sum of all Smart Signals weights. See more details here: https://docs.fingerprint.com/docs/suspect-score

​
tampering
boolean

The field can be used as a standalone flag for tampering detection. Alternatively, the more granular fields documented below can be used for workflows that require more context.

  • true if tampering is detected through an anomalous browser signature, anti-detect browser detection, or other tampering-related methods
  • false if none of the tampering checks return a positive result
​
tampering_confidence
enum<string>

The confidence level indicates how certain Fingerprint is that the current request involves browser tampering. This confidence level is determined by evaluating multiple factors, such as heuristic rules, probabilistic anomaly detection, an anti detect browser ml model, and other relevant methods. It is conveyed as a string with possible values such as high, medium, or low In case of tampering: true

  • High confidence: heuristic anti detect browser signals and the ml model are triggered, or all of the methods are triggered.
  • Medium confidence: either the ml model triggers alone, the anomaly score triggers alone with or without the heuristic anti detect browser methods trigger.
  • Low confidence: only the heuristic anti detect methods are triggered.

In case of tampering: false

  • High confidence: Strong signals suggest the user is not tampering with their request.
Available options:
low,
medium,
high
​
tampering_ml_score
number<double>

The output of this model is captured as tampering_ml_score, a number indicating how likely an event is coming from an anti detect browser. Values close to 1 signify higher confidence and we consider anything above the threshold of 0.8 to be actionable (the result and anti_detect_browser fields conveniently captures that fact)

Required range: 0 <= x <= 1
​
tampering_details
object
​
velocity
object

Sums key data points for a specific visitor_id, ip_address and linked_id at three distinct time intervals: 5 minutes, 1 hour, and 24 hours as follows:

  • Number of distinct IP addresses associated to the visitor Id.
  • Number of distinct linked Ids associated with the visitor Id.
  • Number of distinct countries associated with the visitor Id.
  • Number of identification events associated with the visitor Id.
  • Number of identification events associated with the detected IP address.
  • Number of distinct IP addresses associated with the provided linked Id.
  • Number of distinct visitor Ids associated with the provided linked Id.

The 24h interval of distinct_ip, distinct_linked_id, distinct_country, distinct_ip_by_linked_id and distinct_visitor_id_by_linked_id will be omitted if the number of events for the visitor Id in the last 24 hours (events.['24h']) is higher than 20.000.

All will not necessarily be returned in a response, some may be omitted if the associated event does not have the required data, such as a linked_id.

​
virtual_machine
boolean

true if the request came from a browser running inside a virtual machine (e.g. VMWare), false otherwise.

​
virtual_machine_ml_score
number<double>

Machine learning–based virtual machine score, represented as a floating-point value between 0 and 1 (inclusive), with up to three decimal places of precision. A higher score means a higher confidence in the positive virtual_machine detection result. This Smart Signal is currently in beta and only available to select customers. If you are interested, please contact our support team.

Required range: 0 <= x <= 1
​
vpn
boolean

VPN or other anonymizing service has been used when sending the request.

​
vpn_confidence
enum<string>

A confidence rating for the VPN detection result — "low", "medium", or "high". Depends on the combination of results returned from all VPN detection methods.

Available options:
low,
medium,
high
​
vpn_origin_timezone
string

Local timezone which is used in timezone_mismatch method.

​
vpn_origin_country
string

Country of the request (only for Android SDK version >= 2.4.0, ISO 3166 format or unknown).

​
vpn_methods
object
​
high_activity_device
boolean

Flag indicating if the request came from a high-activity visitor.

​
rare_device
boolean

true if the device is considered rare based on its combination of hardware and software attributes. A device is classified as rare if it falls within the top 99.9 percentile (lowest-frequency segment) of observed traffic, or if its configuration has not been previously seen (not_seen).

This Smart Signal is currently in beta and only available to select customers. If you are interested, please contact our support team.

​
rare_device_percentile_bucket
enum<string>

The rarity percentile bucket of the device, indicating how uncommon the device configuration is compared to all observed devices.

This Smart Signal is currently in beta and only available to select customers. If you are interested, please contact our support team.

Available options:
<p95,
p95-p99,
p99-p99.5,
p99.5-p99.9,
p99.9+,
not_seen
​
raw_device_attributes
object

A curated subset of raw browser/device attributes that the API surface exposes. Each property contains a value or object with the data for the collected signal.

​
labels
object[]

Each label returns a prediction (true or false) for a specific use case (label field) based on a machine learning score. The machine learning score is determined by a model trained on customer data for that use case. This field is in the beta phase and only available to select customers. If you are interested, please contact our support team.

Response

200

Return a 200 status to indicate that the data was received successfully