{ "openapi": "3.1.1", "info": { "title": "Server API", "description": "Fingerprint Server API allows you to get, search, and update Events in a server environment. It can be used for data exports, decision-making, and data analysis scenarios.\nServer API is intended for server-side usage, it's not intended to be used from the client side, whether it's a browser or a mobile device.\nThe API also supports collection of Automation Intelligence for requests to your server in edge, pre-origin, or middleware contexts.\n", "version": "4", "contact": { "name": "Fingerprint Support", "email": "support@fingerprint.com" }, "license": { "name": "MIT", "url": "https://github.com/fingerprintjs/openapi/blob/main/LICENSE" } }, "tags": [ { "name": "Fingerprint", "description": "Using the Server API you can retrieve information about individual analysis events or event history of individual visitors.", "externalDocs": { "description": "API documentation", "url": "https://docs.fingerprint.com/reference/server-api" } } ], "servers": [ { "url": "https://api.fpjs.io/v4", "description": "Global" }, { "url": "https://eu.api.fpjs.io/v4", "description": "EU" }, { "url": "https://ap.api.fpjs.io/v4", "description": "Asia (Mumbai)" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/events/{event_id}": { "get": { "tags": [ "Fingerprint" ], "operationId": "getEvent", "summary": "Get an event by event ID", "description": "Get a detailed analysis of an individual identification event, including Smart Signals.\n\nUse `event_id` as the URL path parameter. This API method is scoped to a request, i.e. all returned information is by `event_id`.\n", "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string", "examples": [ "1708102555327.NLOjmg" ], "example": "1708102555327.NLOjmg" }, "description": "The unique [identifier](https://docs.fingerprint.com/reference/js-agent-get-function#event_id) of each identification request (`requestId` can be used in its place)." }, { "name": "ruleset_id", "in": "query", "required": false, "schema": { "type": "string", "examples": [ "D6N9Kbk9HRWrIWGz" ], "example": "D6N9Kbk9HRWrIWGz" }, "description": "The ID of the ruleset to evaluate against the event, producing the action to take for this event.\nThe resulting action is returned in the `rule_action` attribute of the response.\n" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "400": { "description": "Bad request. The event ID provided is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden. Access to this API is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. The event ID cannot be found in this workspace's data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests. The request is throttled.\nTo protect service stability during rare periods of extreme load, we may return HTTP 429 responses with message `too many search requests` even if you are within your assigned rate limits.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Workspace error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout. Search execution exceeded the allowed timeout window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Fingerprint" ], "operationId": "updateEvent", "summary": "Update an event", "description": "Change information in existing events specified by `event_id` or *flag suspicious events*.\n\nWhen an event is created, it can be assigned `linked_id` and `tags` submitted through the JS agent parameters. \nThis information might not have been available on the client initially, so the Server API permits updating these attributes after the fact.\n\n**Warning** It's not possible to update events older than one month. \n\n**Warning** Trying to update an event immediately after creation may temporarily result in an \nerror (HTTP 409 Conflict. The event is not mutable yet.) as the event is fully propagated across our systems. In such a case, simply retry the request.\n", "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string", "examples": [ "1708102555327.NLOjmg" ], "example": "1708102555327.NLOjmg" }, "description": "The unique event [identifier](https://docs.fingerprint.com/reference/js-agent-get-function#event_id)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventUpdate" } } } }, "responses": { "200": { "description": "OK." }, "400": { "description": "Bad request. The request payload is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden. Access to this API is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. The event ID cannot be found in this workspace's data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict. The event is not mutable yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/events": { "get": { "tags": [ "Fingerprint" ], "operationId": "searchEvents", "x-dotnet-use-request-object": true, "summary": "Search events", "description": "## Search\n\nThe `/v4/events` endpoint provides a convenient way to search for past events based on specific parameters. Typical use cases and queries include:\n\n- Searching for events associated with a single `visitor_id` within a time range to get historical behavior of a visitor.\n- Searching for events associated with a single `linked_id` within a time range to get all events associated with your internal account identifier.\n- Excluding all bot traffic from the query (`good` and `bad` bots)\n\nBy default, the API searches events from the last 7 days, sorts them by newest first and returns the last 10 events.\n\n- Use `start` and `end` to specify the time range of the search.\n- Use `reverse=true` to sort the results oldest first.\n- Use `limit` to specify the number of events to return.\n- Use `pagination_key` to get the next page of results if there are more than `limit` events.\n\n### Filtering events with the `suspect` flag\n\nThe `/v4/events` endpoint unlocks a powerful method for fraud protection analytics. The `suspect` flag is exposed in all events where it was previously set by the update API.\n\nYou can also apply the `suspect` query parameter as a filter to find all potentially fraudulent activity that you previously marked as `suspect`. This helps identify patterns of fraudulent behavior.\n\n### Environment scoping\n\nIf you use a secret key that is scoped to an environment, you will only get events associated with the same environment. With a workspace-scoped environment, you will get events from all environments.\n\nSmart Signals not activated for your workspace or are not included in the response.\n", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 100, "examples": [ 10 ], "example": 10 }, "description": "Maximum number of events to return. Defaults to 10 when omitted. Results are selected from the time range (`start`, `end`), ordered by `reverse`, then truncated to provided `limit` size. So `reverse=true` returns the oldest N=`limit` events, otherwise the newest N=`limit` events.\n" }, { "name": "pagination_key", "in": "query", "schema": { "type": "string", "examples": [ "S9rgMMUb4z3X5t5pr_tSgoSZlmyF0O8X7kCV2m981-iY1LmRTjraa1rTk3L-hQExnDWCi0RA-zAIjaVSTNO2AN2eqQWgzT0RjbieMxRfSdkM-HmOhdOgdQvYfPG3vqU1DJKh4Q" ], "example": "S9rgMMUb4z3X5t5pr_tSgoSZlmyF0O8X7kCV2m981-iY1LmRTjraa1rTk3L-hQExnDWCi0RA-zAIjaVSTNO2AN2eqQWgzT0RjbieMxRfSdkM-HmOhdOgdQvYfPG3vqU1DJKh4Q" }, "description": "Use `pagination_key` to get the next page of results.\n\nWhen more results are available (e.g., you requested up to 100 results for your query using `limit`, but there are more than 100 events total matching your request), the `pagination_key` field is added to the response. The pagination key is an arbitrary string that should not be interpreted in any way and should be passed as-is. In the following request, use that value in the `pagination_key` parameter to get the next page of results:\n\n1. First request, returning most recent 100 events: `GET api-base-url/events?limit=100`\n2. Use `response.pagination_key` to get the next page of results: `GET api-base-url/events?limit=100&pagination_key=S9rgMMUb4z3X5t5pr_tSgoSZlmyF0O8X7kCV2m981-iY1LmRTjraa1rTk3L-hQExnDWCi0RA-zAIjaVSTNO2AN2eqQWgzT0RjbieMxRfSdkM-HmOhdOgdQvYfPG3vqU1DJKh4Q`\n" }, { "name": "visitor_id", "in": "query", "schema": { "type": "string", "examples": [ "Ibk1527CUFmcnjLwIs4A9" ], "example": "Ibk1527CUFmcnjLwIs4A9" }, "description": "Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals.\n\nFilter events by matching Visitor ID (`identification.visitor_id` property).\n" }, { "name": "high_recall_id", "in": "query", "schema": { "type": "string", "examples": [ "Ibk1527CUFmcnjLwIs4A9" ], "example": "Ibk1527CUFmcnjLwIs4A9" }, "description": "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.\n\nFilter events by matching High Recall ID (`supplementary_id_high_recall.visitor_id` property).\n" }, { "name": "bot", "in": "query", "schema": { "$ref": "#/components/schemas/SearchEventsBot" }, "description": "Filter events by the Bot Detection result, specifically:\n `all` - events where any kind of bot was detected.\n `good` - events where a good bot was detected.\n `bad` - events where a bad bot was detected.\n `none` - events where no bot was detected.\n> Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response.\n" }, { "name": "bot_info", "in": "query", "schema": { "$ref": "#/components/schemas/SearchEventsBotInfo" }, "description": "Filter events by their Bot Info result, specifically:\n - `all` - events where any kind of bot was detected.\n - `none` - events where no bot was detected, and no `bot_info` was present.\n" }, { "name": "bot_info_category", "in": "query", "style": "form", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BotInfoCategory" } }, "description": "Filter events by their Bot Info Category.\n\nMultiple categories can be provided using the repeated keys syntax. For example, `bot_info_category=ai_agent&bot_info_category=ai_assistant`, will match events with a Bot Info Category of `ai_agent` or `ai_assistant`. Other notations like comma-separated or bracket notation are not supported.\n" }, { "name": "bot_info_identity", "in": "query", "style": "form", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BotInfoIdentity" } }, "description": "Filter events by their Bot Info Identity type.\n\nMultiple identity types can be provided using the repeated keys syntax. For example, `bot_info_identity=verified&bot_info_identity=signed`, will match events with a Bot Info Identity of `verified` or `signed`. Other notations like comma-separated or bracket notation are not supported.\n" }, { "name": "bot_info_confidence", "in": "query", "style": "form", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BotInfoConfidence" } }, "description": "Filter events by their Bot Info Confidence.\n\nMultiple confidences can be provided using the repeated keys syntax. For example, `bot_info_confidence=high&bot_info_confidence=medium`, will match events with a Bot Info Confidence of `high` or `medium`. Other notations like comma-separated or bracket notation are not supported.\n" }, { "name": "bot_info_provider", "in": "query", "style": "form", "schema": { "type": "array", "items": { "type": "string", "examples": [ "OpenAI" ], "example": "OpenAI" } }, "description": "Filter events by their Bot Info Provider. The provider must match exactly, partial or wildcard matching is not supported.\n\nMultiple Providers can be provided using the repeated keys syntax. For example, `bot_info_provider=OpenAI&bot_info_provider=AWS`, will match events with a Bot Info Provider of `OpenAI` or `AWS`. Other notations like comma-separated or bracket notation are not supported.\n" }, { "name": "bot_info_name", "in": "query", "style": "form", "schema": { "type": "array", "items": { "type": "string", "examples": [ "ChatGPT-User" ], "example": "ChatGPT-User" } }, "description": "Filter events by their Bot Info Name. The name must match exactly, partial or wildcard matching is not supported.\n\nMultiple Names can be provided using the repeated keys syntax. For example, `bot_info_name=ChatGPT%20Agent&bot_info_name=Bedrock%20AgentCore`, will match events with a Bot Info Name of `ChatGPT Agent` or `Bedrock AgentCore`. Other notations like comma-separated or bracket notation are not supported.\n" }, { "name": "ip_address", "in": "query", "schema": { "type": "string", "examples": [ "61.127.217.15" ], "example": "61.127.217.15" }, "description": "Filter events by IP address or IP range (if CIDR notation is used). If CIDR notation is not used, a /32 for IPv4 or /128 for IPv6 is assumed.\nExamples of range based queries: 10.0.0.0/24, 192.168.0.1/32\n" }, { "name": "asn", "in": "query", "schema": { "type": "string", "examples": [ "12876" ], "example": "12876" }, "description": "Filter events by the ASN associated with the event's IP address.\nThis corresponds to the `ip_info.(v4|v6).asn` property in the response.\n" }, { "name": "linked_id", "in": "query", "schema": { "type": "string", "examples": [ "somelinkedId" ], "example": "somelinkedId" }, "description": "Filter events by your custom identifier.\n\nYou can use [linked IDs](https://docs.fingerprint.com/reference/js-agent-get-function#linkedid) to associate identification requests with your own identifier, for example, session ID, purchase ID, or transaction ID. You can then use this `linked_id` parameter to retrieve all events associated with your custom identifier.\n" }, { "name": "url", "in": "query", "schema": { "type": "string", "examples": [ "https://example.com/login" ], "example": "https://example.com/login" }, "description": "Filter events by the URL (`url` property) associated with the event.\n" }, { "name": "bundle_id", "in": "query", "schema": { "type": "string", "examples": [ "com.example.app" ], "example": "com.example.app" }, "description": "Filter events by the Bundle ID (iOS) associated with the event.\n" }, { "name": "package_name", "in": "query", "schema": { "type": "string", "examples": [ "com.example.app" ], "example": "com.example.app" }, "description": "Filter events by the Package Name (Android) associated with the event.\n" }, { "name": "origin", "in": "query", "schema": { "type": "string", "examples": [ "https://example.com" ], "example": "https://example.com" }, "description": "Filter events by the origin field of the event. This is applicable to web events only (e.g., https://example.com)\n" }, { "name": "start", "in": "query", "schema": { "oneOf": [ { "type": "string", "format": "date-time", "examples": [ "2026-01-01T00:00:00Z" ], "example": "2026-01-01T00:00:00Z" }, { "type": "integer", "format": "int64", "examples": [ 1767225600000 ], "example": 1767225600000 } ], "examples": [ "2026-01-01T00:00:00Z" ], "example": "2026-01-01T00:00:00Z" }, "description": "Include events that happened after the provided `start` date formatted as an RFC3339 timestamp. For backward compatibility, a Unix milliseconds timestamp is also accepted. Defaults to 7 days ago. Setting `start` does not change the default `end` date of `now` — adjust it separately if needed.\n" }, { "name": "end", "in": "query", "schema": { "oneOf": [ { "type": "string", "format": "date-time", "examples": [ "2026-01-31T23:59:59Z" ], "example": "2026-01-31T23:59:59Z" }, { "type": "integer", "format": "int64", "examples": [ 1769903999000 ], "example": 1769903999000 } ], "examples": [ "2026-01-31T23:59:59Z" ], "example": "2026-01-31T23:59:59Z" }, "description": "Include events that happened before the provided `end` date formatted as an RFC3339 timestamp. For backward compatibility, a Unix milliseconds timestamp is also accepted. Defaults to now. Setting `end` does not change the default `start` date of `7 days ago` — adjust it separately if needed.\n" }, { "name": "reverse", "in": "query", "schema": { "type": "boolean" }, "description": "When `true`, sort events oldest first (ascending timestamp order). Defaults to `false` (newest first, descending timestamp order).\n" }, { "name": "suspect", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events previously tagged as suspicious via the [Update API](https://docs.fingerprint.com/reference/server-api-v4-update-event).\n> Note: When using this parameter, only events with the `suspect` property explicitly set to `true` or `false` are returned. Events with undefined `suspect` property are left out of the response.\n" }, { "name": "vpn", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by VPN Detection result.\n> Note: When using this parameter, only events with the `vpn` property set to `true` or `false` are returned. Events without a `vpn` Smart Signal result are left out of the response.\n" }, { "name": "virtual_machine", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Virtual Machine Detection result.\n> Note: When using this parameter, only events with the `virtual_machine` property set to `true` or `false` are returned. Events without a `virtual_machine` Smart Signal result are left out of the response.\n" }, { "name": "tampering", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Browser Tampering Detection result.\n> Note: When using this parameter, only events with the `tampering` property set to `true` or `false` are returned. Events without a `tampering` Smart Signal result are left out of the response.\n" }, { "name": "anti_detect_browser", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Anti-detect Browser Detection result.\n> Note: When using this parameter, only events with the `tampering_details.anti_detect_browser` property set to `true` or `false` are returned. Events without a `tampering` Smart Signal result are left out of the response.\n" }, { "name": "incognito", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Browser Incognito Detection result.\n> Note: When using this parameter, only events with the `incognito` property set to `true` or `false` are returned. Events without an `incognito` Smart Signal result are left out of the response.\n" }, { "name": "privacy_settings", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Privacy Settings Detection result.\n> Note: When using this parameter, only events with the `privacy_settings` property set to `true` or `false` are returned. Events without a `privacy_settings` Smart Signal result are left out of the response.\n" }, { "name": "jailbroken", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Jailbroken Device Detection result.\n> Note: When using this parameter, only events with the `jailbroken` property set to `true` or `false` are returned. Events without a `jailbroken` Smart Signal result are left out of the response.\n" }, { "name": "frida", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Frida Detection result.\n> Note: When using this parameter, only events with the `frida` property set to `true` or `false` are returned. Events without a `frida` Smart Signal result are left out of the response.\n" }, { "name": "factory_reset", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Factory Reset Detection result.\n> Note: When using this parameter, only events with a `factory_reset_timestamp` property populated are included. Events without a `factory_reset_timestamp` Smart Signal result are left out of the response.\n" }, { "name": "cloned_app", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Cloned App Detection result.\n> Note: When using this parameter, only events with the `cloned_app` property set to `true` or `false` are returned. Events without a `cloned_app` Smart Signal result are left out of the response.\n" }, { "name": "emulator", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Android Emulator Detection result.\n> Note: When using this parameter, only events with the `emulator` property set to `true` or `false` are returned. Events without an `emulator` Smart Signal result are left out of the response.\n" }, { "name": "root_apps", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Rooted Device Detection result.\n> Note: When using this parameter, only events with the `root_apps` property set to `true` or `false` are returned. Events without a `root_apps` Smart Signal result are left out of the response.\n" }, { "name": "vpn_confidence", "in": "query", "schema": { "$ref": "#/components/schemas/SearchEventsVpnConfidence" }, "description": "Filter events by VPN Detection result confidence level.\n`high` - events with high VPN Detection confidence.\n`medium` - events with medium VPN Detection confidence.\n`low` - events with low VPN Detection confidence.\n> Note: When using this parameter, only events with the `vpn.confidence` property set to a valid value are returned. Events without a `vpn` Smart Signal result are left out of the response.\n" }, { "name": "min_suspect_score", "in": "query", "schema": { "type": "number", "format": "float", "examples": [ 7.5 ], "example": 7.5 }, "description": "Filter events with Suspect Score result above a provided minimum threshold.\n> Note: When using this parameter, only events where the `suspect_score` property set to a value exceeding your threshold are returned. Events without a `suspect_score` Smart Signal result are left out of the response.\n" }, { "name": "developer_tools", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Developer Tools detection result.\n> Note: When using this parameter, only events with the `developer_tools` property set to `true` or `false` are returned. Events without a `developer_tools` Smart Signal result are left out of the response.\n" }, { "name": "location_spoofing", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Location Spoofing detection result.\n> Note: When using this parameter, only events with the `location_spoofing` property set to `true` or `false` are returned. Events without a `location_spoofing` Smart Signal result are left out of the response.\n" }, { "name": "mitm_attack", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by MITM (Man-in-the-Middle) Attack detection result.\n> Note: When using this parameter, only events with the `mitm_attack` property set to `true` or `false` are returned. Events without a `mitm_attack` Smart Signal result are left out of the response.\n" }, { "name": "rare_device", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Device Rarity detection result.\n> Note: When using this parameter, only events with the `rare_device` property set to `true` or `false` are returned. Events without a Device Rarity Smart Signal result are left out of the response.\n\n> This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/).\n" }, { "name": "rare_device_percentile_bucket", "in": "query", "schema": { "$ref": "#/components/schemas/SearchEventsRareDevicePercentileBucket" }, "description": "Filter events by Device Rarity percentile bucket.\n` This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/).\n" }, { "name": "proxy", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Proxy detection result.\n> Note: When using this parameter, only events with the `proxy` property set to `true` or `false` are returned. Events without a `proxy` Smart Signal result are left out of the response.\n" }, { "name": "sdk_version", "in": "query", "schema": { "type": "string", "examples": [ "3.11.14" ], "example": "3.11.14" }, "description": "Filter events by a specific SDK version associated with the identification event (`sdk.version` property). Example: `3.11.14`\n" }, { "name": "sdk_platform", "in": "query", "schema": { "$ref": "#/components/schemas/SearchEventsSdkPlatform" }, "description": "Filter events by the SDK Platform associated with the identification event (`sdk.platform` property) .\n`js` - Javascript agent (Web).\n`ios` - Apple iOS based devices.\n`android` - Android based devices.\n" }, { "name": "environment", "in": "query", "description": "Filter for events by providing one or more environment IDs (`environment_id` property).\n\n### Array syntax\nTo provide multiple environment IDs, use the repeated keys syntax (`environment=env1&environment=env2`).\nOther notations like comma-separated (`environment=env1,env2`) or bracket notation (`environment[]=env1&environment[]=env2`) are not supported.\n", "required": false, "schema": { "type": "array", "items": { "type": "string", "examples": [ "ae_47abaca3db2c7c43" ], "example": "ae_47abaca3db2c7c43" } }, "style": "form" }, { "name": "proximity_id", "in": "query", "schema": { "type": "string", "examples": [ "C9rJYBlOFsAfBwQ" ], "example": "C9rJYBlOFsAfBwQ" }, "description": "Filter events by the most precise Proximity ID provided by default.\n> Note: When using this parameter, only events with the `proximity.id` property matching the provided ID are returned. Events without a `proximity` result are left out of the response.\n" }, { "name": "total_hits", "in": "query", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 1000, "examples": [ 100 ], "example": 100 }, "description": "When set, the response will include a `total_hits` property with a count of total query matches across all pages, up to the specified limit.\n" }, { "name": "tor_node", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Tor Node detection result.\n> Note: When using this parameter, only events with the `tor_node` property set to `true` or `false` are returned. Events without a `tor_node` detection result are left out of the response.\n" }, { "name": "incremental_identification_status", "in": "query", "schema": { "$ref": "#/components/schemas/SearchEventsIncrementalIdentificationStatus" }, "description": "Filter events by their incremental identification status (`incremental_identification_status` property). Non incremental identification events are left out of the response.\n" }, { "name": "simulator", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by iOS Simulator Detection result.\n\n> Note: When using this parameter, only events with the `simulator` property set to `true` or `false` are returned. Events without a `simulator` Smart Signal result are left out of the response.\n" }, { "name": "active_call", "in": "query", "schema": { "type": "boolean" }, "description": "Filter events by Active Call Detection result on mobile devices.\n\n> Note: When using this parameter, only events with the `active_call` property set to `true` or `false` are returned. Events without an `active_call` Smart Signal result are left out of the response.\n" }, { "name": "source", "in": "query", "required": false, "schema": { "type": "array", "maxItems": 1, "items": { "$ref": "#/components/schemas/SearchEventsSource" } }, "description": "Selects the source of events to search. When omitted, only traditional identification events generated from devices are returned (the default behavior). When set to `edge`, only Automation Intelligence (Edge) events are returned.\n\nTo retrieve all events regardless of source, you must make two requests. One with the `source` parameter set to `edge`, and another with the `source` parameter omitted.\n\n> Note: The Automation Intelligence API is in public preview testing phase. If you encounter any issues, please [contact](https://fingerprint.com/support/) our support team.\n" } ], "responses": { "200": { "description": "Events matching the filter(s).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventSearch" } } } }, "400": { "description": "Bad request. One or more supplied search parameters are invalid, or a required parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden. Access to this API is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. The requested visitor does not exist in this workspace's data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests. The request is throttled.\nTo protect service stability during rare periods of extreme load, we may return HTTP 429 responses with message `too many search requests` even if you are within your assigned rate limits.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Workspace error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout. Search execution exceeded the allowed timeout window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/visitors/{visitor_id}": { "delete": { "tags": [ "Fingerprint" ], "operationId": "deleteVisitorData", "summary": "Delete a visitor ID", "description": "Use this API to request the deletion of all data associated with a specific visitor ID.\n\nUpon a request to delete data for a visitor ID,\n- The data collected from the corresponding browser (or device) will be deleted asynchronously, typically within a few minutes. This data will no longer be available to identify this browser (or device). When the same browser (or device) revisits, it will receive a new visitor ID.\n- The identification events made from this browser (or device) in the past 10 days are typically deleted within 24 hrs. \n- The identification events made from this browser (or device) outside of the 10 days will be purged as per your [data retention period](https://docs.fingerprint.com/docs/regions#data-retention).\n\nThe following timeline illustrates which events are deleted and which remain after a DELETE API request:\n```\nDay 1: First visit from browser A. (Assigned visitor ID: VID1000)\nDay 2: Browser A revisits. (Assigned the same visitor ID: VID1000)\nDay 13: Browser A revisits. (Assigned the same visitor ID: VID1000)\nDay 14: Delete VID1000\nDay 15: Browser A re-visits. (Assigned a different visitor ID: VID9999)\nDay 15: GET /events/day-13 (Returns 404. The event is within the 10 days of deleting VID1000 and will have been deleted)\nDay 16: GET /events/day-2 (Returns 200. The event is outside of the 10 days of deleting VID1000 and is still available)\n```\n\n### Availability\nThis API is available only for Enterprise plans **upon request**. If you are interested, please [contact our support team](https://fingerprint.com/support/).\n\n### Rate limits and daily quota\nThe rate limits and daily quota for this API **differ** from those for our other API.\n\nThe maximum number of DELETE requests that can be made in an hour cannot exceed 30 RPH, and the maximum number that can be made in a day cannot exceed 500 RPD.\n\nYou can request an increase to these limits by contacting [our support team](https://fingerprint.com/support/). \n", "parameters": [ { "name": "visitor_id", "in": "path", "required": true, "schema": { "type": "string", "examples": [ "Ibk1527CUFmcnjLwIs4A9" ], "example": "Ibk1527CUFmcnjLwIs4A9" }, "description": "The [visitor ID](https://docs.fingerprint.com/reference/js-agent-get-function#visitor_id) you want to delete." } ], "responses": { "200": { "description": "OK. The visitor ID is scheduled for deletion." }, "400": { "description": "Bad request. The visitor ID parameter is missing or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden. Access to this API is denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. The visitor ID cannot be found in this workspace's data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests. The request is throttled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "string", "description": "Add your Secret API Key to the Authorization header using the standard Bearer format: `Authorization: Bearer `" } }, "schemas": { "LinkedId": { "type": "string", "examples": [ "somelinkedId" ], "description": "A customer-provided ID that was sent with the request." }, "Tags": { "type": "object", "description": "A customer-provided value or an object that was sent with the identification request or updated later.", "additionalProperties": true, "required": [] }, "EventId": { "type": "string", "examples": [ "1708102555327.NLOjmg" ], "description": "Unique identifier of the user's request. The first portion of the event_id is a unix epoch milliseconds timestamp.\n" }, "Timestamp": { "description": "Timestamp of the event with millisecond precision in Unix time.", "type": "integer", "format": "int64", "examples": [ 1708102555327 ] }, "EventSource": { "type": "string", "description": "Identifies how the event was generated.\n- `device` - the event was generated by the JS agent or a mobile SDK running on an end-user device.\n- `edge` - the event was generated by the Automation Intelligence API (`/edge` endpoint), analyzing a request intercepted at the edge.\n", "enum": [ "device", "edge" ] }, "Url": { "type": "string", "examples": [ "https://www.example.com/login" ], "description": "Page URL from which the request was sent." }, "BotInfoCategory": { "type": "string", "enum": [ "advertising_and_marketing", "aggregator", "ai_agent", "ai_assistant", "ai_browser", "ai_crawler", "ai_search", "browser_automation", "ecommerce", "monitoring_and_analytics", "other", "scraping", "security", "search_engine_crawler", "search_engine_optimization", "unknown" ], "description": "The type and purpose of the bot.\n" }, "BotInfoIdentity": { "type": "string", "enum": [ "verified", "signed", "spoofed", "unknown" ], "description": "The verification status of the bot's identity:\n * `verified` - well-known bot with publicly verifiable identity, directed by the bot provider.\n * `signed` - bot that signs its platform via Web Bot Auth, directed by the bot provider's customers.\n * `spoofed` - bot that claims a public identity but fails verification.\n * `unknown` - bot that does not publish a verifiable identity.\n" }, "BotInfoConfidence": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Confidence level of the bot identification." }, "BotInfo": { "type": "object", "description": "Extended bot information.", "required": [ "category", "provider", "name", "identity", "confidence" ], "properties": { "category": { "type": "string", "description": "The type and purpose of the bot.\n" }, "provider": { "type": "string", "description": "The organization or company operating the bot.", "examples": [ "Anthropic", "Browserbase", "Google", "OpenAI" ] }, "provider_url": { "type": "string", "examples": [ "https://chatgpt.com" ], "description": "The URL of the bot provider's website." }, "name": { "type": "string", "description": "The specific name or identifier of the bot.", "examples": [ "ClaudeBot", "Browserbase Agent", "Googlebot", "GPTBot", "ChatGPT-User" ] }, "identity": { "type": "string", "enum": [ "verified", "signed", "spoofed", "unknown" ], "description": "The verification status of the bot's identity:\n * `verified` - well-known bot with publicly verifiable identity, directed by the bot provider.\n * `signed` - bot that signs its platform via Web Bot Auth, directed by the bot provider's customers.\n * `spoofed` - bot that claims a public identity but fails verification.\n * `unknown` - bot that does not publish a verifiable identity.\n" }, "confidence": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Confidence level of the bot identification." } } }, "Geolocation": { "type": "object", "required": [], "properties": { "accuracy_radius": { "type": "integer", "examples": [ 20 ], "minimum": 0, "description": "The IP address is likely to be within this radius (in km) of the specified location." }, "latitude": { "type": "number", "format": "double", "examples": [ 50.05 ], "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "format": "double", "examples": [ 14.4 ], "minimum": -180, "maximum": 180 }, "postal_code": { "type": "string", "examples": [ "150 00" ] }, "timezone": { "type": "string", "format": "timezone", "examples": [ "Europe/Prague" ] }, "city_name": { "type": "string", "examples": [ "Prague" ] }, "country_code": { "type": "string", "examples": [ "CZ" ], "minLength": 2, "maxLength": 2 }, "country_name": { "type": "string", "examples": [ "Czechia" ] }, "continent_code": { "type": "string", "examples": [ "EU" ], "minLength": 2, "maxLength": 2 }, "continent_name": { "type": "string", "examples": [ "Europe" ] }, "subdivisions": { "type": "array", "items": { "type": "object", "required": [ "iso_code", "name" ], "properties": { "iso_code": { "type": "string", "examples": [ "10" ] }, "name": { "type": "string", "examples": [ "Hlavni mesto Praha" ] } } } } } }, "IPInfoV4": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "format": "ipv4", "examples": [ "94.142.239.124" ] }, "geolocation": { "$ref": "#/components/schemas/Geolocation" }, "asn": { "type": "string", "examples": [ "396982", "16509", "701" ] }, "asn_name": { "type": "string", "examples": [ "Google LLC", "Amazon.com, Inc.", "Verizon Business" ] }, "asn_network": { "type": "string", "examples": [ "34.160.0.0/12", "3.208.0.0/12", "173.56.0.0/16" ] }, "asn_type": { "type": "string", "examples": [ "hosting", "isp", "business", "education" ] }, "datacenter_result": { "type": "boolean", "description": "When true, the request originated from a datacenter." }, "datacenter_name": { "type": "string", "examples": [ "Google Cloud", "Amazon AWS" ] } } }, "IPInfoV6": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "format": "ipv6", "examples": [ "2001:db8:3333:4444:5555:6666:7777:8888" ] }, "geolocation": { "$ref": "#/components/schemas/Geolocation" }, "asn": { "type": "string", "examples": [ "396982", "16509", "701" ] }, "asn_name": { "type": "string", "examples": [ "Google LLC", "Amazon.com, Inc.", "Verizon Business" ] }, "asn_network": { "type": "string", "examples": [ "2001:4860:4801:10::/64", "2600:1f00::/24", "2001:4868:800::/40" ] }, "asn_type": { "type": "string", "examples": [ "hosting", "isp", "business", "education" ] }, "datacenter_result": { "type": "boolean", "description": "When true, the request originated from a datacenter." }, "datacenter_name": { "type": "string", "examples": [ "Google Cloud", "Amazon AWS" ] } } }, "IPInfo": { "type": "object", "description": "Details about the request IP address. Has separate fields for v4 and v6 IP address versions.", "required": [], "properties": { "v4": { "$ref": "#/components/schemas/IPInfoV4" }, "v6": { "$ref": "#/components/schemas/IPInfoV6" } } }, "Proxy": { "type": "boolean", "description": "IP address was used by a public proxy provider or belonged to a known recent residential proxy\n" }, "ProxyConfidence": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "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\".\n" }, "ProxyDetails": { "type": "object", "description": "Proxy detection details (present if `proxy` is `true`)", "required": [ "proxy_type" ], "properties": { "proxy_type": { "type": "string", "enum": [ "residential", "data_center", "unknown" ], "description": "Proxy type:\n * `residential` - proxies that route through residential and telecom IP addresses to appear as legitimate traffic\n * `data_center` - proxies which route through data centers\n * `unknown` - reported when a proxy is detected solely by the ML model and the IP sources did not determine a specific type\n" }, "last_seen_at": { "type": "integer", "format": "int64", "examples": [ 1708102555327 ], "description": "Unix millisecond timestamp with hourly resolution of when this IP was last seen as a proxy\n" }, "provider": { "type": "string", "examples": [ "Massive" ], "description": "String representing the last proxy service provider detected when this\nIP was synced. An IP can be shared by multiple service providers.\n" } } }, "Vpn": { "type": "boolean", "description": "VPN or other anonymizing service has been used when sending the request.\n" }, "VpnConfidence": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "A confidence rating for the VPN detection result — \"low\", \"medium\", or \"high\". Depends on the combination of results returned from all VPN detection methods." }, "VpnMethods": { "type": "object", "required": [], "properties": { "timezone_mismatch": { "type": "boolean", "x-platforms": [ "android", "ios", "browser" ], "description": "The browser timezone doesn't match the timezone inferred from the request IP address." }, "public_vpn": { "type": "boolean", "x-platforms": [ "android", "ios", "browser" ], "description": "Request IP address is owned and used by a public VPN service provider." }, "auxiliary_mobile": { "type": "boolean", "x-platforms": [ "android", "ios", "browser" ], "description": "This method applies to mobile devices only. Indicates the result of additional methods used to detect a VPN in mobile devices." }, "os_mismatch": { "type": "boolean", "x-platforms": [ "browser" ], "description": "The browser runs on a different operating system than the operating system inferred from the request network signature." }, "relay": { "type": "boolean", "x-platforms": [ "android", "ios", "browser" ], "description": "Request IP address belongs to a relay service provider, indicating the use of relay services like [Apple Private relay](https://support.apple.com/en-us/102602) or [Cloudflare Warp](https://developers.cloudflare.com/warp-client/).\n\n* Like VPNs, relay services anonymize the visitor's true IP address.\n* Unlike traditional VPNs, relay services don't let visitors spoof their location by choosing an exit node in a different country.\n\nThis field allows you to differentiate VPN users and relay service users in your fraud prevention logic.\n" }, "ml_prediction": { "type": "boolean", "x-platforms": [ "browser" ], "description": "`true` if the request came from a device running a VPN, `false` otherwise. \n" } } }, "ErrorCode": { "type": "string", "enum": [ "request_cannot_be_parsed", "request_read_timeout", "secret_api_key_required", "secret_api_key_not_found", "public_api_key_required", "public_api_key_not_found", "subscription_not_active", "wrong_region", "feature_not_enabled", "visitor_not_found", "too_many_requests", "state_not_ready", "failed", "event_not_found", "missing_module", "payload_too_large", "service_unavailable", "ruleset_not_found" ], "description": "Error code:\n* `request_cannot_be_parsed` - The query parameters or JSON payload contains some errors\n that prevented us from parsing it (wrong type/surpassed limits).\n* `request_read_timeout` - The request body could not be read before the connection timed out.\n* `secret_api_key_required` - secret API key in header is missing or empty.\n* `secret_api_key_not_found` - No Fingerprint workspace found for specified secret API key.\n* `public_api_key_required` - public API key in header is missing or empty.\n* `public_api_key_not_found` - No Fingerprint workspace found for specified public API key.\n* `subscription_not_active` - Fingerprint workspace is not active.\n* `wrong_region` - Server and workspace region differ.\n* `feature_not_enabled` - This feature (for example, Delete API) is not enabled for your workspace.\n* `visitor_not_found` - The specified visitor ID was not found. It never existed or it may have already been deleted.\n* `too_many_requests` - The limit on secret API key requests per second has been exceeded.\n* `state_not_ready` - The event specified with event ID is\n not ready for updates yet. Try again.\n This error happens in rare cases when update API is called immediately\n after receiving the event ID on the client. In case you need to send\n information right away, we recommend using the JS agent API instead.\n* `failed` - Internal server error.\n* `event_not_found` - The specified event ID was not found. It never existed, expired, or it has been deleted.\n* `missing_module` - The request is invalid because it is missing a required module.\n* `payload_too_large` - The request payload is too large and cannot be processed.\n* `service_unavailable` - The service was unable to process the request.\n* `ruleset_not_found` - The specified ruleset was not found. It never existed or it has been deleted.\n" }, "Error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string", "examples": [ "Forbidden" ] } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/Error" } } }, "IncrementalIdentificationStatus": { "type": "string", "description": "Only included for requests using incremental identification.\n- `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.\n- `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. \n", "enum": [ "partially_completed", "completed" ] }, "EnvironmentId": { "type": "string", "examples": [ "ae_47abaca3db2c7c43" ], "description": "Environment ID of the event." }, "Suspect": { "type": "boolean", "description": "Field is `true` if you have previously set the `suspect` flag for this event using the [Server API Update event endpoint](https://docs.fingerprint.com/reference/server-api-update-event)." }, "Integration": { "type": "object", "required": [], "properties": { "name": { "type": "string", "examples": [ "fingerprint-pro-react" ], "description": "The name of the specific integration." }, "version": { "type": "string", "examples": [ "3.11.10" ], "description": "The version of the specific integration." }, "subintegration": { "type": "object", "required": [], "properties": { "name": { "type": "string", "examples": [ "preact" ], "description": "The name of the specific subintegration." }, "version": { "type": "string", "examples": [ "10.21.0" ], "description": "The version of the specific subintegration." } } } } }, "SDK": { "type": "object", "description": "Contains information about the SDK used to perform the request.", "required": [ "platform", "version" ], "properties": { "platform": { "type": "string", "enum": [ "js", "android", "ios", "unknown" ], "description": "Platform of the SDK used for the identification request." }, "version": { "type": "string", "examples": [ "3.11.10" ], "description": "Version string of the SDK used for the identification request." }, "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } }, "Replayed": { "type": "boolean", "description": "`true` if we determined that this payload was replayed, `false` otherwise.\n" }, "IdentificationConfidence": { "type": "object", "description": "The confidence score represents the probability of a false-positive identification. To learn more, visit [Confidence Score](https://docs.fingerprint.com/docs/identification-accuracy-and-confidence#confidence-score). Please note that the confidence score is not yet supported for [High Recall ID](https://docs.fingerprint.com/docs/supplementary-identifiers-highrecall). ", "required": [ "score" ], "properties": { "score": { "type": "number", "format": "double", "examples": [ 0.97 ], "minimum": 0, "maximum": 1, "description": "A floating-point number between 0 and 1 that represents the probability of a false-positive identification. For High Recall ID, this value is 0. " }, "version": { "type": "string", "examples": [ "1.1" ], "description": "The version name of the method used to calculate the confidence score. For High Recall ID, this value is \"Not Supported\". " }, "comment": { "type": "string", "examples": [ "Low confidence due to bot signals" ] } } }, "Identification": { "type": "object", "required": [ "visitor_id", "visitor_found" ], "properties": { "visitor_id": { "type": "string", "examples": [ "Ibk1527CUFmcnjLwIs4A9" ], "description": "String of 20 characters that uniquely identifies the visitor's browser or mobile device." }, "confidence": { "$ref": "#/components/schemas/IdentificationConfidence" }, "visitor_found": { "type": "boolean", "description": "Attribute represents if a visitor had been identified before." }, "first_seen_at": { "type": "integer", "format": "int64", "examples": [ 1708102555327 ], "description": "Unix epoch time milliseconds timestamp indicating the time at which this visitor ID was first seen. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000\n" }, "last_seen_at": { "type": "integer", "format": "int64", "examples": [ 1708102555327 ], "description": "Unix epoch time milliseconds timestamp indicating the time at which this visitor ID was last seen. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000\n" } } }, "SupplementaryIDHighRecall": { "type": "object", "description": "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.", "required": [ "visitor_id", "visitor_found" ], "properties": { "visitor_id": { "type": "string", "examples": [ "0jnGMkPYXX37DqVa4ZIO3f_hr" ], "description": "The High Recall identifier for the visitor's browser. It is an alphanumeric string with a maximum length of 25 characters." }, "visitor_found": { "type": "boolean", "description": "True if this is a returning browser and has been previously identified. Otherwise, false." }, "confidence": { "$ref": "#/components/schemas/IdentificationConfidence" }, "first_seen_at": { "type": "integer", "format": "int64", "examples": [ 1778086556130 ], "description": "Unix epoch timestamp (in milliseconds) indicating when the browser was first identified. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000\n" }, "last_seen_at": { "type": "integer", "format": "int64", "examples": [ 1778604975494 ], "description": "Unix epoch timestamp (in milliseconds) corresponding to the most recent visit by this browser. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000\n" } } }, "BundleId": { "type": "string", "examples": [ "com.foo.app" ], "description": "Bundle ID of the iOS application integrated with the Fingerprint SDK for the event.\n" }, "PackageName": { "type": "string", "examples": [ "com.foo.app" ], "description": "Package name of the Android application integrated with the Fingerprint SDK for the event.\n" }, "IpAddress": { "type": "string", "examples": [ "61.127.217.15" ], "description": "IP address of the requesting browser or bot." }, "UserAgent": { "type": "string", "examples": [ "Mozilla/5.0 (Windows NT 6.1; Win64; x64) ...." ], "description": "User Agent of the client." }, "Device": { "type": "string", "examples": [ "Generic Smartphone", "Desktop", "iPhone" ], "description": "Device model or family extracted from the user agent string. On web, this field is also present inside `browser_details`.\n" }, "Os": { "type": "string", "examples": [ "Windows", "iOS", "Android" ], "description": "Operating system family extracted from the user agent string. On web, this field is also present inside `browser_details`.\n" }, "OsVersion": { "type": "string", "examples": [ "17.4", "14", "10" ], "description": "Operating system version string extracted from the user agent string. On web, this field is also present inside `browser_details`.\n" }, "ClientReferrer": { "type": "string", "examples": [ "https://example.com/blog/my-article" ], "description": "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).\n" }, "BrowserDetails": { "type": "object", "required": [ "browser_name", "browser_full_version", "browser_major_version", "os", "os_version", "device" ], "properties": { "browser_name": { "type": "string", "examples": [ "Chrome" ] }, "browser_major_version": { "type": "string", "examples": [ "74" ] }, "browser_full_version": { "type": "string", "examples": [ "74.0.3729" ] }, "os": { "type": "string", "examples": [ "Windows" ] }, "os_version": { "type": "string", "examples": [ "7" ] }, "device": { "type": "string", "examples": [ "Other" ] } } }, "Proximity": { "type": "object", "description": "Proximity ID represents a fixed geographical zone in a discrete global grid within which the device is observed.\n", "required": [ "id", "precision_radius", "confidence" ], "properties": { "id": { "type": "string", "examples": [ "w1aTfd4MCvl" ], "description": "A stable privacy-preserving identifier for a given proximity zone.\n" }, "precision_radius": { "type": "integer", "format": "int32", "enum": [ 10, 25, 65, 175, 450, 1200, 3300, 8500, 22500 ], "description": "The radius of the proximity zone’s precision level, in meters.\n" }, "confidence": { "type": "number", "format": "float", "examples": [ 0.95 ], "minimum": 0, "maximum": 1, "description": "A value between `0` and `1` representing the likelihood that the true device location lies within the mapped proximity zone.\n * Scores closer to `1` indicate high confidence that the location is inside the mapped proximity zone.\n * Scores closer to `0` indicate lower confidence, suggesting the true location may fall in an adjacent zone.\n" } } }, "ActiveCall": { "type": "boolean", "description": "Indicates whether the mobile device had an active call (cellular or VoIP) at the time of the request. Available from SDK 2.16.0+ on iOS and Android.\n" }, "BotResult": { "type": "string", "enum": [ "bad", "good", "not_detected" ], "description": "Bot detection result:\n * `bad` - bad bot detected, such as Selenium, Puppeteer, Playwright, headless browsers, and so on\n * `good` - good bot detected, such as Google bot, Baidu Spider, AlexaBot and so on\n * `not_detected` - the visitor is not a bot\n" }, "BotType": { "type": "string", "examples": [ "chatgpt_agent" ], "description": "Additional classification of the bot type if detected.\n" }, "ClonedApp": { "type": "boolean", "description": "Android specific cloned application detection. There are 2 values: \n* `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).\n* `false` - No signs of cloned application detected or the client is not Android.\n" }, "DeveloperTools": { "type": "boolean", "description": "`true` if the browser has DevTools open (Chrome, Firefox) or the Android/iOS device has Developer Tools enabled, `false` otherwise.\n" }, "DeviceDetails": { "type": "object", "description": "Native, SDK-collected mobile device identification signals (manufacturer, model, and OS version). Structurally separate from the top-level `device`, `os`, and `os_version` fields and from `browser_details`, all of which are derived from user-agent parsing rather than native SDK signals.", "required": [], "properties": { "device_manufacturer": { "type": "string", "examples": [ "samsung", "Apple" ], "description": "Raw device manufacturer string as reported by the device OS. Not normalized: casing is vendor-defined (samsung, Xiaomi, OPPO, HUAWEI). Always `Apple` on iOS." }, "device_model": { "type": "string", "examples": [ "SM-G991U", "D84AP" ], "description": "Raw device model identifier, as reported by the mobile OS. On Android, this is the vendor-defined model string (e.g., `SM-G991U`). On iOS, this is an Apple board code (e.g., `D84AP`)." }, "os_version": { "type": "string", "examples": [ "9", "16.1", "8.1.0", "17.4.1" ], "description": "Mobile operating system version. Component count is not fixed and must not be assumed by consumers: iOS always reports `major.minor.patch` (e.g. `17.4.1`), while Android's precision varies by OS era and which raw signal resolved it — `major` only (`9`, `13`) since Android 10 dropped point releases, `major.minor` (`16.1`) from Android 16 (API 36+) reintroducing a minor component, or a genuine `major.minor.patch` (`8.1.0`) on pre-Android 10 devices that shipped real point releases. Never a fabricated/zero-padded component." } } }, "Emulator": { "type": "boolean", "description": "Android specific emulator detection. There are 2 values: \n* `true` - Emulated environment detected (e.g. launch inside of AVD). \n* `false` - No signs of emulated environment detected or the client is not Android.\n" }, "FactoryReset": { "type": "integer", "format": "int64", "examples": [ 1708102555327 ], "description": "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](https://docs.fingerprint.com/docs/smart-signals-reference#factory-reset-detection) to learn more about this Smart Signal.\n" }, "Frida": { "type": "boolean", "description": "[Frida](https://frida.re/docs/) detection for Android and iOS devices. There are 2 values:\n* `true` - Frida detected\n* `false` - No signs of Frida or the client is not a mobile device.\n" }, "IPBlockList": { "type": "object", "required": [], "properties": { "email_spam": { "type": "boolean", "description": "IP address was part of a known email spam attack (SMTP)." }, "attack_source": { "type": "boolean", "description": "IP address was part of a known network attack (SSH/HTTPS)." }, "tor_node": { "type": "boolean", "description": "IP address was part of known TOR network activity." } } }, "ProxyMLScore": { "type": "number", "format": "double", "examples": [ 0.2 ], "minimum": 0, "maximum": 1, "description": "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](https://fingerprint.com/support/).\n" }, "Incognito": { "type": "boolean", "description": "`true` if we detected incognito mode used in the browser, `false` otherwise.\n" }, "Jailbroken": { "type": "boolean", "description": "iOS specific jailbreak detection. There are 2 values: \n* `true` - Jailbreak detected.\n* `false` - No signs of jailbreak or the client is not iOS.\n" }, "LocationSpoofing": { "type": "boolean", "description": "Flag indicating whether the request came from a mobile device with location spoofing enabled." }, "MitMAttack": { "type": "boolean", "description": "* `true` - When requests made from your users' mobile devices to Fingerprint servers have been intercepted and potentially modified. \n* `false` - Otherwise or when the request originated from a browser.\nSee [MitM Attack Detection](https://docs.fingerprint.com/docs/smart-signals-reference#mitm-attack-detection) to learn more about this Smart Signal.\n" }, "PrivacySettings": { "type": "boolean", "description": "`true` if the request is from a privacy aware browser (e.g. Tor) or from a browser in which fingerprinting is blocked. Otherwise `false`.\n" }, "RootApps": { "type": "boolean", "description": "Android specific root management apps detection. There are 2 values: \n* `true` - Root Management Apps detected (e.g. Magisk).\n* `false` - No Root Management Apps detected or the client isn't Android.\n" }, "RulesetId": { "type": "string", "examples": [ "rs_b1k1blhqpOX3kU" ], "description": "The ID of the evaluated ruleset." }, "RuleId": { "type": "string", "examples": [ "r_uE0af8497PFAOD" ], "description": "The ID of the rule that matched the identification event." }, "RuleExpression": { "type": "string", "examples": [ "bot in [\"bad\"] || incognito" ], "description": "The expression of the rule that matched the identification event." }, "RuleActionType": { "type": "string", "description": "Describes the action to take with the request.", "enum": [ "allow", "block" ] }, "RuleActionHeaderField": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "examples": [ "Content-Type" ], "description": "The header field name." }, "value": { "type": "string", "examples": [ "application/json" ], "description": "The value of the header field." } } }, "RequestHeaderModifications": { "type": "object", "description": "The set of header modifications to apply, in the following order: remove, set, append.", "required": [], "properties": { "remove": { "type": "array", "description": "The list of headers to remove.", "items": { "type": "string", "examples": [ "X-Forwarded-For" ] } }, "set": { "type": "array", "description": "The list of headers to set, overwriting any existing headers with the same name.", "items": { "$ref": "#/components/schemas/RuleActionHeaderField" } }, "append": { "type": "array", "description": "The list of headers to append.", "items": { "$ref": "#/components/schemas/RuleActionHeaderField" } } } }, "EventRuleActionAllow": { "description": "Informs the client that the request should be forwarded to the origin with optional request header modifications.", "type": "object", "properties": { "ruleset_id": { "$ref": "#/components/schemas/RulesetId" }, "rule_id": { "$ref": "#/components/schemas/RuleId" }, "rule_expression": { "$ref": "#/components/schemas/RuleExpression" }, "type": { "allOf": [ { "$ref": "#/components/schemas/RuleActionType" }, { "const": "allow" } ] }, "request_header_modifications": { "$ref": "#/components/schemas/RequestHeaderModifications" } }, "required": [ "ruleset_id", "type" ] }, "StatusCode": { "type": "integer", "examples": [ 200 ], "description": "A valid HTTP status code." }, "RuleActionBody": { "type": "string", "examples": [ "{\"title\":\"Forbidden\"}" ], "description": "The response body to send to the client." }, "EventRuleActionBlock": { "description": "Informs the client the request should be blocked using the response described by this rule action.", "type": "object", "properties": { "ruleset_id": { "$ref": "#/components/schemas/RulesetId" }, "rule_id": { "$ref": "#/components/schemas/RuleId" }, "rule_expression": { "$ref": "#/components/schemas/RuleExpression" }, "type": { "allOf": [ { "$ref": "#/components/schemas/RuleActionType" }, { "const": "block" } ] }, "status_code": { "$ref": "#/components/schemas/StatusCode" }, "headers": { "type": "array", "description": "A list of headers to send.", "items": { "$ref": "#/components/schemas/RuleActionHeaderField" } }, "body": { "$ref": "#/components/schemas/RuleActionBody" } }, "required": [ "ruleset_id", "type" ] }, "EventRuleAction": { "type": "object", "description": "Describes the action the client should take, according to the rule in the ruleset that matched the event. When getting an event by event ID, the rule_action will only be included when the ruleset_id query parameter is specified.", "oneOf": [ { "$ref": "#/components/schemas/EventRuleActionAllow" }, { "$ref": "#/components/schemas/EventRuleActionBlock" } ], "discriminator": { "propertyName": "type", "mapping": { "allow": "#/components/schemas/EventRuleActionAllow", "block": "#/components/schemas/EventRuleActionBlock" } } }, "Simulator": { "type": "boolean", "description": "iOS specific simulator detection. There are 2 values:\n* `true` - Simulator environment detected.\n* `false` - No signs of simulator or the client is not iOS.\n" }, "SuspectScore": { "type": "integer", "examples": [ 8 ], "description": "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\n" }, "Tampering": { "type": "boolean", "description": "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.\n* `true` if tampering is detected through an anomalous browser signature, anti-detect browser detection, or other tampering-related methods\n* `false` if none of the tampering checks return a positive result\n" }, "TamperingConfidence": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "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\nIn case of tampering: `true`\n* **High confidence**: heuristic anti detect browser signals and the ml model are triggered, or all of the methods are triggered.\n* **Medium confidence**: either the ml model triggers alone, the anomaly score triggers alone with or without the heuristic anti detect browser methods trigger.\n* **Low confidence**: only the heuristic anti detect methods are triggered.\n\nIn case of tampering: `false`\n* **High confidence:** Strong signals suggest the user is not tampering with their request.\n" }, "TamperingMlScore": { "type": "number", "format": "double", "examples": [ 0.5 ], "minimum": 0, "maximum": 1, "description": "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)\n" }, "TamperingDetails": { "type": "object", "required": [], "properties": { "anomaly_score": { "type": "number", "format": "double", "examples": [ 0.5 ], "minimum": 0, "maximum": 1, "x-platforms": [ "android", "ios", "browser" ], "description": "The output of this model is captured as anomaly_score, a statistical score indicating how rare the visitor's browser signature is compared to the overall population. Values close to 1 signify highly anomalous browsers and we consider anything above the threshold of 0.5 to be actionable (the result field conveniently captures that fact).\n" }, "anti_detect_browser": { "type": "boolean", "x-platforms": [ "browser" ], "description": "Detects whether the request shows evidence of anti-detect browser usage.\nThis field may be triggered by:\n* heuristic detection of known anti-detect browser behavior\n* machine learning detection of anti-detect browser patterns\n\nExamples of anti-detect browsers include tools such as AdsPower, DolphinAnty, OctoBrowser, and GoLogin.\n" } } }, "VelocityData": { "type": "object", "description": "Is absent if the velocity data could not be generated for the visitor ID.\n", "required": [ "5_minutes", "1_hour" ], "properties": { "5_minutes": { "type": "integer", "examples": [ 1 ], "description": "Count for the last 5 minutes of velocity data, from the time of the event.\n" }, "1_hour": { "type": "integer", "examples": [ 5 ], "description": "Count for the last 1 hour of velocity data, from the time of the event.\n" }, "24_hours": { "type": "integer", "examples": [ 5 ], "description": "Count for the last 24 hours of velocity data, from the time of the event.\n" } } }, "Velocity": { "type": "object", "description": "Sums key data points for a specific `visitor_id`, `ip_address` and `linked_id` at three distinct time\nintervals: 5 minutes, 1 hour, and 24 hours as follows: \n\n- Number of distinct IP addresses associated to the visitor ID.\n- Number of distinct linked IDs associated with the visitor ID.\n- Number of distinct countries associated with the visitor ID.\n- Number of identification events associated with the visitor ID.\n- Number of identification events associated with the detected IP address.\n- Number of distinct IP addresses associated with the provided linked ID.\n- Number of distinct visitor IDs associated with the provided linked ID.\n\nThe `24_hours` interval of `distinct_ip`, `distinct_linked_id`, `distinct_country`,\n`distinct_ip_by_linked_id` and `distinct_visitor_id_by_linked_id` will be omitted \nif the number of `events` for the visitor ID in the last 24\nhours (`events.['24_hours']`) is higher than 20.000.\n\nAll will not necessarily be returned in a response, some may be omitted if the \nassociated event does not have the required data, such as a linked_id.\n", "required": [], "properties": { "distinct_ip": { "$ref": "#/components/schemas/VelocityData" }, "distinct_linked_id": { "$ref": "#/components/schemas/VelocityData" }, "distinct_country": { "$ref": "#/components/schemas/VelocityData" }, "events": { "$ref": "#/components/schemas/VelocityData" }, "ip_events": { "$ref": "#/components/schemas/VelocityData" }, "distinct_ip_by_linked_id": { "$ref": "#/components/schemas/VelocityData" }, "distinct_visitor_id_by_linked_id": { "$ref": "#/components/schemas/VelocityData" } } }, "VirtualMachine": { "type": "boolean", "description": "`true` if the request came from a browser running inside a virtual machine (e.g. VMWare), `false` otherwise.\n" }, "VirtualMachineMLScore": { "type": "number", "format": "double", "examples": [ 0.5 ], "minimum": 0, "maximum": 1, "description": "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](https://fingerprint.com/support/).\n" }, "VpnMLScore": { "type": "number", "format": "double", "examples": [ 0.2 ], "minimum": 0, "maximum": 1, "description": "Machine learning–based VPN 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 `vpn` detection result. This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/).\n" }, "VpnOriginTimezone": { "type": "string", "examples": [ "Europe/Berlin" ], "description": "Local timezone which is used in timezone_mismatch method.\n" }, "VpnOriginCountry": { "type": "string", "examples": [ "DE" ], "description": "Country of the request (Android SDK version >= 2.4.0, iOS SDK version >= 2.9.0, JS agent >= 3.12.9 / 4.0.2), ISO 3166 format or unknown.\n" }, "HighActivity": { "type": "boolean", "description": "Flag indicating if the request came from a high-activity visitor." }, "RareDevice": { "type": "boolean", "description": "`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`).\n> This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/).\n" }, "RareDevicePercentileBucket": { "type": "string", "description": "The rarity percentile bucket of the device, indicating how uncommon the device configuration is compared to all observed devices. \n> This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/).\n", "enum": [ " Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response.\n" }, "SearchEventsBotInfo": { "type": "string", "enum": [ "all", "none" ], "description": "Filter events by their Bot Info result, specifically:\n - `all` - events where any kind of bot was detected.\n - `none` - events where no bot was detected, and no `bot_info` was present.\n" }, "SearchEventsVpnConfidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Filter events by VPN Detection result confidence level.\n`high` - events with high VPN Detection confidence.\n`medium` - events with medium VPN Detection confidence.\n`low` - events with low VPN Detection confidence.\n> Note: When using this parameter, only events with the `vpn.confidence` property set to a valid value are returned. Events without a `vpn` Smart Signal result are left out of the response.\n" }, "SearchEventsRareDevicePercentileBucket": { "type": "string", "enum": [ " This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/).\n" }, "SearchEventsSdkPlatform": { "type": "string", "enum": [ "js", "android", "ios" ], "description": "Filter events by the SDK Platform associated with the identification event (`sdk.platform` property) .\n`js` - Javascript agent (Web).\n`ios` - Apple iOS based devices.\n`android` - Android based devices.\n" }, "SearchEventsIncrementalIdentificationStatus": { "type": "string", "enum": [ "partially_completed", "completed" ], "description": "Filter events by their incremental identification status (`incremental_identification_status` property). Non incremental identification events are left out of the response.\n" }, "SearchEventsSource": { "type": "string", "enum": [ "edge" ] } } } }