openapi: 3.0.3 info: title: Server API v3 (deprecated) description: > > 🚧 Deprecation Notice > > This version of Server API is marked as deprecated starting on **Jan 7th 2026** according to our [API Deprecation Policy](https://docs.fingerprint.com/reference/api-deprecation-policy). If you still use this version, please follow our [migration guide](https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4) to migrate from this deprecated version to the new one. Fingerprint Server API allows you to search, update, and delete identification events in a server environment. It can be used for data exports, decision-making, and data analysis scenarios. Server 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. version: '3' 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/v3/server-api servers: - url: https://api.fpjs.io description: Global - url: https://eu.api.fpjs.io description: EU - url: https://ap.api.fpjs.io description: Asia (Mumbai) security: - ApiKeyHeader: [] - ApiKeyQuery: [] paths: /events/{request_id}: get: tags: - Fingerprint operationId: getEvent summary: Get event by request ID description: > > 🚧 Deprecation Notice > > This version of Server API is marked as deprecated starting on **Jan 7th 2026** according to our [API Deprecation Policy](https://docs.fingerprint.com/reference/api-deprecation-policy). If you still use this version, please follow our [migration guide](https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4#migrating-get-/events) to migrate from this deprecated version to the new one. Get a detailed analysis of an individual identification event, including Smart Signals. Please note that the response includes mobile signals (e.g. `rootApps`) even if the request originated from a non-mobile platform. It is highly recommended that you **ignore** the mobile signals for such requests. Use `requestId` as the URL path parameter. This API method is scoped to a request, i.e. all returned information is by `requestId`. parameters: - name: request_id in: path required: true schema: type: string description: >- The unique [identifier](https://docs.fingerprint.com/reference/v3/js-agent-get-function#requestid) of each identification request. responses: '200': description: OK. content: application/json: schema: $ref: '#/components/schemas/EventsGetResponse' '403': description: Forbidden. Access to this API is denied. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- Not found. The request ID cannot be found in this application's data. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: > Too Many Requests. The request is throttled. To 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. 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' put: tags: - Fingerprint operationId: updateEvent summary: Update an event with a given request ID description: > > 🚧 Deprecation Notice > > This version of Server API is marked as deprecated starting on **Jan 7th 2026** according to our [API Deprecation Policy](https://docs.fingerprint.com/reference/api-deprecation-policy). If you still use this version, please follow our [migration guide](https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4#migrating-update-/events) to migrate from this deprecated version to the new one. Change information in existing events specified by `requestId` or *flag suspicious events*. When an event is created, it is assigned `linkedId` and `tag` submitted through the JS agent parameters. This information might not be available on the client so the Server API allows for updating the attributes after the fact. **Warning** It's not possible to update events older than 10 days. parameters: - name: request_id in: path required: true schema: type: string description: >- The unique event [identifier](https://docs.fingerprint.com/reference/v3/js-agent-get-function#requestid). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EventsUpdateRequest' 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 request ID cannot be found in this application'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/search: get: tags: - Fingerprint operationId: searchEvents summary: Get events via search description: > > 🚧 Deprecation Notice > > This version of Server API is marked as deprecated starting on **Jan 7th 2026** according to our [API Deprecation Policy](https://docs.fingerprint.com/reference/api-deprecation-policy). If you still use this version, please follow our [migration guide](https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4#migrating-get-/events/search) to migrate from this deprecated version to the new one. Search for identification events, including Smart Signals, using multiple filtering criteria. If you don't provide `start` or `end` parameters, the default search range is the last 7 days. Please note that events include mobile signals (e.g. `rootApps`) even if the request originated from a non-mobile platform. We recommend you **ignore** mobile signals for such requests. parameters: - name: limit in: query required: true schema: type: integer format: int32 minimum: 1 example: 10 description: | Limit the number of events returned. - name: pagination_key in: query schema: type: string description: > Use `pagination_key` to get the next page of results. When more results are available (e.g., you requested up to 200 results for your search using `limit`, but there are more than 200 events total matching your request), the `paginationKey` top-level attribute is added to the response. The key corresponds to the `timestamp` of the last returned event. In the following request, use that value in the `pagination_key` parameter to get the next page of results: 1. First request, returning most recent 200 events: `GET api-base-url/events/search?limit=200` 2. Use `response.paginationKey` to get the next page of results: `GET api-base-url/events/search?limit=200&pagination_key=1740815825085` - name: visitor_id in: query schema: type: string description: > Unique [visitor identifier](https://docs.fingerprint.com/reference/v3/js-agent-get-function#visitorid) issued by Fingerprint Identification and all active Smart Signals. Filter for events matching this `visitor_id`. - name: bot in: query schema: type: string enum: - all - good - bad - none description: > Filter events by the Bot Detection result, specifically: `all` - events where any kind of bot was detected. `good` - events where a good bot was detected. `bad` - events where a bad bot was detected. `none` - events where no bot was detected. > Note: When using this parameter, only events with the `products.botd.data.bot.result` property set to a valid value are returned. Events without a `products.botd` Smart Signal result are left out of the response. - name: ip_address in: query schema: type: string description: > Filter events by IP address range. The range can be as specific as a single IP (/32 for IPv4 or /128 for IPv6) All ip_address filters must use CIDR notation, for example, 10.0.0.0/24, 192.168.0.1/32 - name: linked_id in: query schema: type: string description: > Filter events by your custom identifier. You can use [linked IDs](https://docs.fingerprint.com/reference/v3/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. - name: start in: query schema: type: integer format: int64 description: > Filter events with a timestamp greater than the start time, in Unix time (milliseconds). - name: end in: query schema: type: integer format: int64 description: > Filter events with a timestamp smaller than the end time, in Unix time (milliseconds). - name: reverse in: query schema: type: boolean default: false description: > When `true`, sort events oldest first (ascending timestamp order). Default is newest first (descending timestamp order). - name: suspect in: query schema: type: boolean description: > Filter events previously tagged as suspicious via the [Update API](https://docs.fingerprint.com/reference/v3/server-api-update-event). > 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. - name: vpn in: query schema: type: boolean description: > Filter events by VPN Detection result. > Note: When using this parameter, only events with the `products.vpn.data.result` property set to `true` or `false` are returned. Events without a `products.vpn` Smart Signal result are left out of the response. - name: virtual_machine in: query schema: type: boolean description: > Filter events by Virtual Machine Detection result. > Note: When using this parameter, only events with the `products.virtualMachine.data.result` property set to `true` or `false` are returned. Events without a `products.virtualMachine` Smart Signal result are left out of the response. - name: tampering in: query schema: type: boolean description: > Filter events by Tampering Detection result. > Note: When using this parameter, only events with the `products.tampering.data.result` property set to `true` or `false` are returned. Events without a `products.tampering` Smart Signal result are left out of the response. - name: anti_detect_browser in: query schema: type: boolean description: > Filter events by Anti-detect Browser Detection result. > Note: When using this parameter, only events with the `products.tampering.data.antiDetectBrowser` property set to `true` or `false` are returned. Events without a `products.tampering` Smart Signal result are left out of the response. - name: incognito in: query schema: type: boolean description: > Filter events by Browser Incognito Detection result. > Note: When using this parameter, only events with the `products.incognito.data.result` property set to `true` or `false` are returned. Events without a `products.incognito` Smart Signal result are left out of the response. - name: privacy_settings in: query schema: type: boolean description: > Filter events by Privacy Settings Detection result. > Note: When using this parameter, only events with the `products.privacySettings.data.result` property set to `true` or `false` are returned. Events without a `products.privacySettings` Smart Signal result are left out of the response. - name: jailbroken in: query schema: type: boolean description: > Filter events by Jailbroken Device Detection result. > Note: When using this parameter, only events with the `products.jailbroken.data.result` property set to `true` or `false` are returned. Events without a `products.jailbroken` Smart Signal result are left out of the response. - name: frida in: query schema: type: boolean description: > Filter events by Frida Detection result. > Note: When using this parameter, only events with the `products.frida.data.result` property set to `true` or `false` are returned. Events without a `products.frida` Smart Signal result are left out of the response. - name: factory_reset in: query schema: type: boolean description: > Filter events by Factory Reset Detection result. > Note: When using this parameter, only events with the `products.factoryReset.data.result` property set to `true` or `false` are returned. Events without a `products.factoryReset` Smart Signal result are left out of the response. - name: cloned_app in: query schema: type: boolean description: > Filter events by Cloned App Detection result. > Note: When using this parameter, only events with the `products.clonedApp.data.result` property set to `true` or `false` are returned. Events without a `products.clonedApp` Smart Signal result are left out of the response. - name: emulator in: query schema: type: boolean description: > Filter events by Android Emulator Detection result. > Note: When using this parameter, only events with the `products.emulator.data.result` property set to `true` or `false` are returned. Events without a `products.emulator` Smart Signal result are left out of the response. - name: root_apps in: query schema: type: boolean description: > Filter events by Rooted Device Detection result. > Note: When using this parameter, only events with the `products.rootApps.data.result` property set to `true` or `false` are returned. Events without a `products.rootApps` Smart Signal result are left out of the response. - name: vpn_confidence in: query schema: type: string enum: - high - medium - low description: > Filter events by VPN Detection result confidence level. `high` - events with high VPN Detection confidence. `medium` - events with medium VPN Detection confidence. `low` - events with low VPN Detection confidence. > Note: When using this parameter, only events with the `products.vpn.data.confidence` property set to a valid value are returned. Events without a `products.vpn` Smart Signal result are left out of the response. - name: min_suspect_score in: query schema: type: number format: float description: > Filter events with Suspect Score result above a provided minimum threshold. > Note: When using this parameter, only events where the `products.suspectScore.data.result` property set to a value exceeding your threshold are returned. Events without a `products.suspectScore` Smart Signal result are left out of the response. - name: ip_blocklist in: query schema: type: boolean description: > Filter events by IP Blocklist Detection result. > Note: When using this parameter, only events with the `products.ipBlocklist.data.result` property set to `true` or `false` are returned. Events without a `products.ipBlocklist` Smart Signal result are left out of the response. - name: datacenter in: query schema: type: boolean description: > Filter events by Datacenter Detection result. > Note: When using this parameter, only events with the `products.ipInfo.data.v4.datacenter.result` or `products.ipInfo.data.v6.datacenter.result` property set to `true` or `false` are returned. Events without a `products.ipInfo` Smart Signal result are left out of the response. - name: developer_tools in: query schema: type: boolean description: > Filter events by Developer Tools detection result. > Note: When using this parameter, only events with the `products.developerTools.data.result` property set to `true` or `false` are returned. Events without a `products.developerTools` Smart Signal result are left out of the response. - name: location_spoofing in: query schema: type: boolean description: > Filter events by Location Spoofing detection result. > Note: When using this parameter, only events with the `products.locationSpoofing.data.result` property set to `true` or `false` are returned. Events without a `products.locationSpoofing` Smart Signal result are left out of the response. - name: mitm_attack in: query schema: type: boolean description: > Filter events by MITM (Man-in-the-Middle) Attack detection result. > Note: When using this parameter, only events with the `products.mitmAttack.data.result` property set to `true` or `false` are returned. Events without a `products.mitmAttack` Smart Signal result are left out of the response. - name: rare_device in: query schema: type: boolean description: > Filter events by Rare Device detection result. > Note: When using this parameter, only events with the `products.rareDevice.data.result` property set to `true` or `false` are returned. Events without a `products.rareDevice` Smart Signal result are left out of the response. - name: rare_device_percentile_bucket in: query schema: type: string enum: - Filter events by Rare Device percentile bucket. ` Filter events by Proxy detection result. > Note: When using this parameter, only events with the `products.proxy.data.result` property set to `true` or `false` are returned. Events without a `products.proxy` Smart Signal result are left out of the response. - name: sdk_version in: query schema: type: string description: > Filter events by a specific SDK version associated with the identification event. Example: `3.11.14` - name: sdk_platform in: query schema: type: string enum: - js - android - ios description: > Filter events by the SDK Platform associated with the identification event. `js` - JavaScript agent (Web). `ios` - Apple iOS based devices. `android` - Android based devices. - name: environment in: query description: | Filter for events by providing one or more environment IDs. required: false schema: type: array items: type: string style: form explode: true - name: proximity_id in: query schema: type: string description: > Filter events by the most precise Proximity ID provided by default. > Note: When using this parameter, only events with the `products.proximity.id` property matching the provided ID are returned. Events without a `products.proximity` result are left out of the response. - name: proximity_precision_radius in: query schema: type: integer format: int32 enum: - 10 - 25 - 65 - 175 - 450 - 1200 - 3300 - 8500 - 22500 description: > Filter events by Proximity Radius. > Note: When using this parameter, only events with the `products.proximity.precisionRadius` property set to a valid value are returned. Events without a `products.proximity` result are left out of the response. responses: '200': description: Events matching the filter(s). content: application/json: schema: $ref: '#/components/schemas/SearchEventsResponse' '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 application's data. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: > Too Many Requests. The request is throttled. To 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. 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}: get: tags: - Fingerprint operationId: getVisits summary: Get visits by visitor ID description: > > 🚧 Deprecation Notice > > This version of Server API is marked as deprecated starting on **Jan 7th 2026** according to our [API Deprecation Policy](https://docs.fingerprint.com/reference/api-deprecation-policy). If you still use this version, please follow our [migration guide](https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4#migrating-get-/visitors) to migrate from this deprecated version to the new one. This endpoint is deprecated. Use `GET /events/search` to query visit history or filter across multiple events. `GET /visitors/{visitor_id}` currently returns at most one visit in `visits`, even when no filters are provided. Only information from the _Identification_ product is returned. #### Headers * `Retry-After` — Present in case of `429 Too many requests`. Indicates how long you should wait before making a follow-up request. The value is non-negative decimal integer indicating the seconds to delay after the response is received. x-flatten-optional-params: true parameters: - name: visitor_id in: path required: true schema: type: string description: >- Unique [visitor identifier](https://docs.fingerprint.com/reference/v3/js-agent-get-function#visitorid) issued by Fingerprint Identification and all active Smart Signals. - name: request_id in: query schema: type: string description: > Filter visits by `requestId`. Every identification request has a unique identifier associated with it called `requestId`. This identifier is returned to the client in the identification [result](https://docs.fingerprint.com/reference/v3/js-agent-get-function#requestid). When you filter visits by `requestId`, only one visit will be returned. x-go-skip-pointer: true - name: linked_id in: query schema: type: string description: > Filter visits by your custom identifier. You can use [`linkedId`](https://docs.fingerprint.com/reference/v3/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. x-go-skip-pointer: true - name: limit in: query schema: type: integer format: int32 minimum: 0 description: > Limit scanned results. `GET /visitors/{visitor_id}` currently returns at most one visit. Use `GET /events/search` for paginated multi-event queries. x-go-skip-pointer: true - name: paginationKey in: query schema: type: string description: > Deprecated pagination parameter retained for backward compatibility. `GET /visitors/{visitor_id}` currently returns at most one visit, so pagination is not expected. Use `GET /events/search` for paginated results. x-go-skip-pointer: true - name: before in: query deprecated: true schema: type: integer format: int64 minimum: 0 description: > ⚠️ Deprecated pagination method, please use `paginationKey` instead. Timestamp (in milliseconds since epoch) used to paginate results. `GET /visitors/{visitor_id}` currently returns at most one visit, so pagination is not expected. x-go-skip-pointer: true responses: '200': description: OK. content: application/json: schema: $ref: '#/components/schemas/VisitorsGetResponse' '400': description: >- Bad request. The visitor ID or query parameters are missing or in the wrong format. content: application/json: schema: $ref: '#/components/schemas/ErrorPlainResponse' '403': description: Forbidden. Access to this API is denied. content: application/json: schema: $ref: '#/components/schemas/ErrorPlainResponse' '404': description: >- Not found. The visitor ID cannot be found in this application's data. content: application/json: schema: $ref: '#/components/schemas/ErrorPlainResponse' '429': description: > Too Many Requests. The request is throttled. To 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. headers: Retry-After: description: >- Indicates how many seconds you should wait before attempting the next request. schema: type: integer format: int32 minimum: 0 content: application/json: schema: $ref: '#/components/schemas/ErrorPlainResponse' '504': description: >- Gateway Timeout. Search execution exceeded the allowed timeout window. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: tags: - Fingerprint operationId: deleteVisitorData summary: Delete data by visitor ID description: > > 🚧 Deprecation Notice > > This version of Server API is marked as deprecated starting on **Jan 7th 2026** according to our [API Deprecation Policy](https://docs.fingerprint.com/reference/api-deprecation-policy). If you still use this version, please follow our [migration guide](https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4) to migrate from this deprecated version to the new one. Request deleting all data associated with the specified visitor ID. This API is useful for compliance with privacy regulations. ### Which data is deleted? - Browser (or device) properties - Identification requests made from this browser (or device) #### Browser (or device) properties - Represents the data that Fingerprint collected from this specific browser (or device) and everything inferred and derived from it. - Upon request to delete, this data is deleted asynchronously (typically within a few minutes) and it will no longer be used to identify this browser (or device) for your [Fingerprint Workspace](https://docs.fingerprint.com/docs/v3/glossary#fingerprint-workspace). #### Identification requests made from this browser (or device) - Fingerprint stores the identification requests made from a browser (or device) for up to 30 (or 90) days depending on your plan. To learn more, see [Data Retention](https://docs.fingerprint.com/docs/v3/regions#data-retention). - Upon request to delete, the identification requests that were made by this browser - Within the past 10 days are deleted within 24 hrs. - Outside of 10 days are allowed to purge as per your data retention period. ### Corollary After requesting to delete a visitor ID, - If the same browser (or device) requests to identify, it will receive a different visitor ID. - If you request [`/events` API](https://docs.fingerprint.com/reference/v3/server-api-get-event) with a `request_id` that was made outside of the 10 days, you will still receive a valid response. - If you request [`/visitors` API](https://docs.fingerprint.com/reference/v3/server-api-get-visits) for the deleted visitor ID, the response will include identification requests that were made outside of those 10 days. ### Interested? Please [contact our support team](https://fingerprint.com/support/) to enable it for you. Otherwise, you will receive a 403. parameters: - name: visitor_id in: path required: true schema: type: string description: >- The [visitor ID](https://docs.fingerprint.com/reference/v3/js-agent-get-function#visitorid) 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 application'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' /related-visitors: get: tags: - Fingerprint operationId: getRelatedVisitors summary: Get Related Visitors description: > > 🚧 Deprecation Notice > > This version of Server API is marked as deprecated starting on **Jan 7th 2026** according to our [API Deprecation Policy](https://docs.fingerprint.com/reference/api-deprecation-policy). Related visitors API lets you link web visits and in-app browser visits that originated from the same mobile device. It searches the past 6 months of identification events to find the visitor IDs that belong to the same mobile device as the given visitor ID. ⚠️ Please note that this API is not enabled by default and is billable separately. ⚠️ If you would like to use Related visitors API, please contact our [support team](https://fingerprint.com/support). To learn more, see [Related visitors API reference](https://docs.fingerprint.com/reference/related-visitors-api). parameters: - name: visitor_id in: query required: true schema: type: string description: >- The [visitor ID](https://docs.fingerprint.com/reference/v3/js-agent-get-function#visitorid) for which you want to find the other visitor IDs that originated from the same mobile device. responses: '200': description: OK. content: application/json: schema: $ref: '#/components/schemas/RelatedVisitorsResponse' '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 application'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' /webhook: trace: summary: Dummy path to describe webhook format. tags: - Fingerprint description: >- Fake path to describe webhook format. More information about webhooks can be found in the [documentation](https://docs.fingerprint.com/docs/v3/webhooks) x-flatten-optional-params: true requestBody: content: application/json: schema: $ref: '#/components/schemas/Webhook' responses: default: description: Dummy for the schema callbacks: webhook: webhook: post: summary: Webhook example description: >- You can use HTTP basic authentication and set up credentials in your [Fingerprint account](https://dashboard.fingerprint.com/login) requestBody: content: application/json: schema: $ref: '#/components/schemas/Webhook' responses: default: description: The server doesn't validate the answer. components: securitySchemes: ApiKeyHeader: type: apiKey in: header name: Auth-API-Key ApiKeyQuery: type: apiKey in: query name: api_key schemas: BrowserDetails: type: object additionalProperties: false required: - browserName - browserFullVersion - browserMajorVersion - os - osVersion - device - userAgent properties: browserName: type: string browserMajorVersion: type: string browserFullVersion: type: string os: type: string osVersion: type: string device: type: string userAgent: type: string GeolocationCity: type: object additionalProperties: false required: - name properties: name: type: string GeolocationCountry: type: object additionalProperties: false required: - code - name properties: code: type: string minLength: 2 maxLength: 2 name: type: string GeolocationContinent: type: object additionalProperties: false required: - code - name properties: code: type: string minLength: 2 maxLength: 2 name: type: string GeolocationSubdivision: type: object additionalProperties: false required: - isoCode - name properties: isoCode: type: string name: type: string GeolocationSubdivisions: type: array items: $ref: '#/components/schemas/GeolocationSubdivision' DeprecatedGeolocation: deprecated: true type: object description: >- This field is **deprecated** and will not return a result for **applications created after January 23rd, 2024**. Please use the [IP Geolocation Smart signal](https://docs.fingerprint.com/docs/v3/smart-signals-reference#ip-geolocation) for geolocation information. additionalProperties: false properties: accuracyRadius: type: integer minimum: 0 description: >- The IP address is likely to be within this radius (in km) of the specified location. latitude: type: number format: double minimum: -90 maximum: 90 longitude: type: number format: double minimum: -180 maximum: 180 postalCode: type: string timezone: type: string format: timezone city: $ref: '#/components/schemas/GeolocationCity' country: $ref: '#/components/schemas/GeolocationCountry' continent: $ref: '#/components/schemas/GeolocationContinent' subdivisions: $ref: '#/components/schemas/GeolocationSubdivisions' Tag: type: object description: >- A customer-provided value or an object that was sent with identification request. additionalProperties: true IdentificationConfidence: type: object additionalProperties: false required: - score properties: score: type: number format: double minimum: 0 maximum: 1 description: >- The confidence score is a floating-point number between 0 and 1 that represents the probability of accurate identification. revision: type: string description: >- The revision name of the method used to calculate the Confidence score. This field is only present for customers who opted in to an alternative calculation method. comment: type: string IdentificationSeenAt: type: object additionalProperties: false required: - global - subscription properties: global: type: string nullable: true format: date-time x-ogen-time-format: 2006-01-02T15:04:05.000Z07:00 subscription: type: string nullable: true format: date-time x-ogen-time-format: 2006-01-02T15:04:05.000Z07:00 RawDeviceAttributeError: type: object additionalProperties: false properties: name: type: string message: type: string RawDeviceAttribute: type: object additionalProperties: false properties: value: title: value error: $ref: '#/components/schemas/RawDeviceAttributeError' RawDeviceAttributes: type: object description: > It includes 35+ raw browser identification attributes to provide Fingerprint users with even more information than our standard visitor ID provides. This enables Fingerprint users to not have to run our open-source product in conjunction with Fingerprint Pro Plus and Enterprise to get those additional attributes. Warning: The raw signals data can change at any moment as we improve the product. We cannot guarantee the internal shape of raw device attributes to be stable, so typical semantic versioning rules do not apply here. Use this data with caution without assuming a specific structure beyond the generic type provided here. additionalProperties: $ref: '#/components/schemas/RawDeviceAttribute' Integration: type: object additionalProperties: false properties: name: type: string description: The name of the specific integration, e.g. "fingerprint-pro-react". version: type: string description: The version of the specific integration, e.g. "3.11.10". subintegration: type: object additionalProperties: false properties: name: type: string description: The name of the specific subintegration, e.g. "preact". version: type: string description: The version of the specific subintegration, e.g. "10.21.0". SDK: type: object description: Contains information about the SDK used to perform the request. additionalProperties: false required: - platform - version properties: platform: type: string description: Platform of the SDK. version: type: string description: SDK version string. integrations: type: array items: $ref: '#/components/schemas/Integration' Identification: type: object additionalProperties: false required: - visitorId - requestId - browserDetails - incognito - ip - timestamp - time - url - tag - visitorFound - firstSeenAt - lastSeenAt - replayed properties: visitorId: type: string description: >- String of 20 characters that uniquely identifies the visitor's browser or mobile device. requestId: type: string description: Unique identifier of the user's request. browserDetails: $ref: '#/components/schemas/BrowserDetails' incognito: description: Flag if user used incognito session. type: boolean ip: type: string description: IP address of the requesting browser or bot. ipLocation: $ref: '#/components/schemas/DeprecatedGeolocation' linkedId: type: string description: A customer-provided id that was sent with the request. suspect: 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/v3/server-api-update-event). type: boolean timestamp: description: Timestamp of the event with millisecond precision in Unix time. type: integer format: int64 time: type: string format: date-time x-ogen-time-format: 2006-01-02T15:04:05Z07:00 description: >- Time expressed according to ISO 8601 in UTC format, when the request from the JS agent was made. We recommend to treat requests that are older than 2 minutes as malicious. Otherwise, request replay attacks are possible. url: type: string description: Page URL from which the request was sent. tag: $ref: '#/components/schemas/Tag' confidence: $ref: '#/components/schemas/IdentificationConfidence' visitorFound: type: boolean description: Attribute represents if a visitor had been identified before. firstSeenAt: $ref: '#/components/schemas/IdentificationSeenAt' lastSeenAt: $ref: '#/components/schemas/IdentificationSeenAt' components: $ref: '#/components/schemas/RawDeviceAttributes' replayed: type: boolean description: > `true` if we determined that this payload was replayed, `false` otherwise. sdk: $ref: '#/components/schemas/SDK' environmentId: type: string description: Environment ID associated with the event ErrorCode: type: string enum: - RequestCannotBeParsed - RequestReadTimeout - TokenRequired - TokenNotFound - SubscriptionNotActive - WrongRegion - FeatureNotEnabled - WorkspaceScopedSecretKeyRequired - RequestNotFound - VisitorNotFound - TooManyRequests - 429 Too Many Requests - StateNotReady - Failed description: | Error code: * `RequestCannotBeParsed` - the query parameters or JSON payload contains some errors that prevented us from parsing it (wrong type/surpassed limits). * `RequestReadTimeout` - the request body could not be read before the connection timed out. * `TokenRequired` - `Auth-API-Key` header is missing or empty. * `TokenNotFound` - no Fingerprint application found for specified secret key. * `SubscriptionNotActive` - Fingerprint application is not active. * `WrongRegion` - server and application region differ. * `FeatureNotEnabled` - this feature (for example, Delete API) is not enabled for your application. * `WorkspaceScopedSecretKeyRequired` - The provided secret API key is scoped to an environment, but this operation requires a workspace-scoped secret API key. * `RequestNotFound` - the specified request ID was not found. It never existed, expired, or it has been deleted. * `VisitorNotFound` - The specified visitor ID was not found. It never existed or it may have already been deleted. * `TooManyRequests` - the limit on secret API key requests per second has been exceeded. * `429 Too Many Requests` - the limit on secret API key requests per second has been exceeded. * `StateNotReady` - The event specified with request id is not ready for updates yet. Try again. This error happens in rare cases when update API is called immediately after receiving the request id on the client. In case you need to send information right away, we recommend using the JS agent API instead. * `Failed` - internal server error. Error: type: object additionalProperties: false required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string ProductIdentification: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Identification' error: $ref: '#/components/schemas/Error' BotdBotResult: type: string enum: - notDetected - good - bad description: | Bot detection result: * `notDetected` - the visitor is not a bot * `good` - good bot detected, such as Google bot, Baidu Spider, AlexaBot and so on * `bad` - bad bot detected, such as Selenium, Puppeteer, Playwright, headless browsers, and so on BotdBot: type: object description: Stores bot detection result additionalProperties: false required: - result properties: result: $ref: '#/components/schemas/BotdBotResult' type: type: string Botd: type: object description: Contains all the information from Bot Detection product additionalProperties: false required: - bot - url - ip - time - userAgent - requestId properties: bot: $ref: '#/components/schemas/BotdBot' meta: $ref: '#/components/schemas/Tag' linkedId: type: string description: A customer-provided id that was sent with the request. url: type: string description: Page URL from which the request was sent. ip: type: string description: IP address of the requesting browser or bot. time: type: string format: date-time x-ogen-time-format: 2006-01-02T15:04:05.000Z07:00 description: >- Time in UTC when the request from the JS agent was made. We recommend to treat requests that are older than 2 minutes as malicious. Otherwise, request replay attacks are possible. userAgent: type: string requestId: type: string description: Unique identifier of the user's request. ProductBotd: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Botd' error: $ref: '#/components/schemas/Error' RootApps: type: object additionalProperties: false required: - result properties: result: type: boolean description: > 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. ProductRootApps: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/RootApps' error: $ref: '#/components/schemas/Error' Emulator: type: object additionalProperties: false required: - result properties: result: type: boolean description: | 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. ProductEmulator: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Emulator' error: $ref: '#/components/schemas/Error' Geolocation: type: object additionalProperties: false properties: accuracyRadius: type: integer minimum: 0 description: >- The IP address is likely to be within this radius (in km) of the specified location. latitude: type: number format: double minimum: -90 maximum: 90 longitude: type: number format: double minimum: -180 maximum: 180 postalCode: type: string timezone: type: string format: timezone city: $ref: '#/components/schemas/GeolocationCity' country: $ref: '#/components/schemas/GeolocationCountry' continent: $ref: '#/components/schemas/GeolocationContinent' subdivisions: $ref: '#/components/schemas/GeolocationSubdivisions' IPInfoASN: type: object additionalProperties: false required: - asn - name - network properties: asn: type: string name: type: string network: type: string type: type: string IPInfoDataCenter: type: object additionalProperties: false required: - result - name properties: result: type: boolean name: type: string IPInfoV4: type: object additionalProperties: false required: - address - geolocation properties: address: type: string format: ipv4 geolocation: $ref: '#/components/schemas/Geolocation' asn: $ref: '#/components/schemas/IPInfoASN' datacenter: $ref: '#/components/schemas/IPInfoDataCenter' IPInfoV6: type: object additionalProperties: false required: - address - geolocation properties: address: type: string format: ipv6 geolocation: $ref: '#/components/schemas/Geolocation' asn: $ref: '#/components/schemas/IPInfoASN' datacenter: $ref: '#/components/schemas/IPInfoDataCenter' IPInfo: type: object description: >- Details about the request IP address. Has separate fields for v4 and v6 IP address versions. additionalProperties: false properties: v4: $ref: '#/components/schemas/IPInfoV4' v6: $ref: '#/components/schemas/IPInfoV6' ProductIPInfo: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/IPInfo' error: $ref: '#/components/schemas/Error' IPBlocklistDetails: type: object additionalProperties: false required: - emailSpam - attackSource properties: emailSpam: type: boolean description: IP address was part of a known email spam attack (SMTP). attackSource: type: boolean description: IP address was part of a known network attack (SSH/HTTPS). IPBlocklist: type: object additionalProperties: false required: - result - details properties: result: type: boolean description: > `true` if request IP address is part of any database that we use to search for known malicious actors, `false` otherwise. details: $ref: '#/components/schemas/IPBlocklistDetails' ProductIPBlocklist: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/IPBlocklist' error: $ref: '#/components/schemas/Error' Tor: type: object additionalProperties: false required: - result properties: result: type: boolean description: > `true` if the request IP address is a known tor exit node, `false` otherwise. ProductTor: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Tor' error: $ref: '#/components/schemas/Error' 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 additionalProperties: false required: - timezoneMismatch - publicVPN - auxiliaryMobile - osMismatch - relay properties: timezoneMismatch: type: boolean description: >- The browser timezone doesn't match the timezone inferred from the request IP address. publicVPN: type: boolean description: >- Request IP address is owned and used by a public VPN service provider. auxiliaryMobile: type: boolean description: >- This method applies to mobile devices only. Indicates the result of additional methods used to detect a VPN in mobile devices. osMismatch: type: boolean description: >- The browser runs on a different operating system than the operating system inferred from the request network signature. relay: type: boolean 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/). * Like VPNs, relay services anonymize the visitor's true IP address. * Unlike traditional VPNs, relay services don't let visitors spoof their location by choosing an exit node in a different country. This field allows you to differentiate VPN users and relay service users in your fraud prevention logic. mlPrediction: type: boolean description: > `true` if the request came from a device running a VPN, `false` otherwise. VPN: type: object additionalProperties: false required: - result - confidence - originTimezone - originCountry - methods properties: result: type: boolean description: >- VPN or other anonymizing service has been used when sending the request. confidence: $ref: '#/components/schemas/VPNConfidence' mlScore: type: number format: double 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/). originTimezone: type: string description: Local timezone which is used in timezoneMismatch method. originCountry: type: string description: >- Country of the request (only for Android SDK version >= 2.4.0, ISO 3166 format or unknown). methods: $ref: '#/components/schemas/VPNMethods' ProductVPN: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/VPN' error: $ref: '#/components/schemas/Error' 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". ProxyDetails: type: object nullable: true additionalProperties: false description: Proxy detection details (present if proxy is detected) required: - proxyType properties: proxyType: type: string enum: - residential - data_center - unknown description: | Proxy type: * `residential` - proxies that route through residential and telecom IP addresses to appear as legitimate traffic * `data_center` - proxies which route through data centers * `unknown` - reported when a proxy is detected solely by the ML model and the IP sources did not determine a specific type lastSeenAt: type: string format: date-time x-ogen-time-format: '2006-01-02T15:00:00Z' description: | ISO 8601 formatted timestamp in UTC with hourly resolution of when this IP was last seen as a proxy when available. Proxy: type: object additionalProperties: false required: - result - confidence properties: result: type: boolean description: > IP address was used by a public proxy provider or belonged to a known recent residential proxy confidence: $ref: '#/components/schemas/ProxyConfidence' details: $ref: '#/components/schemas/ProxyDetails' mlScore: type: number format: double 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/). ProductProxy: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Proxy' error: $ref: '#/components/schemas/Error' Incognito: type: object additionalProperties: false required: - result properties: result: type: boolean description: > `true` if we detected incognito mode used in the browser, `false` otherwise. ProductIncognito: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Incognito' error: $ref: '#/components/schemas/Error' Tampering: type: object additionalProperties: false required: - result - confidence - anomalyScore - mlScore - antiDetectBrowser properties: result: type: boolean description: > Indicates if an identification request from a browser or an Android SDK has been tampered with. Not supported in the iOS SDK, is always `false` for iOS requests. * `true` - If the request meets either of the following conditions: * Contains anomalous browser or device attributes that could not have been legitimately produced by the JavaScript agent or the Android SDK (see `anomalyScore`). * Originated from an anti-detect browser like Incognition (see `antiDetectBrowser`). * `false` - If the request is considered genuine or was generated by the iOS SDK. confidence: type: string enum: - low - medium - high description: | Confidence level of the tampering detection. If a tampering is not detected, confidence is "high". If it's detected, can be "low", "medium", or "high". anomalyScore: type: number format: double minimum: 0 maximum: 1 description: > A score that indicates the extent of anomalous data in the request. This field applies to requests originating from **both** browsers and Android SDKs. * Values above `0.5` indicate that the request has been tampered with. * Values below `0.5` indicate that the request is genuine. mlScore: type: number format: double minimum: 0 maximum: 1 description: > A score that indicates the models calculated probability that an event is coming from an anti detect browser. * Values above `0.8` indicate that the request is an anti detect browser based on the ml model * Values below `0.8` indicate that the request is not an anti detect browser based on the ml model antiDetectBrowser: type: boolean description: > Anti-detect browsers try to evade identification by masking or manipulating their fingerprint to imitate legitimate browser configurations. This field does not apply to requests originating from mobile SDKs. * `true` - The browser resembles a known anti-detect browser, for example, Incognition. * `false` - The browser does not resemble an anti-detect browser or the request originates from a mobile SDK. ProductTampering: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Tampering' error: $ref: '#/components/schemas/Error' ClonedApp: type: object additionalProperties: false required: - result properties: result: type: boolean description: | 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. ProductClonedApp: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/ClonedApp' error: $ref: '#/components/schemas/Error' FactoryReset: type: object additionalProperties: false required: - time - timestamp properties: time: type: string format: date-time description: > Indicates the time (in UTC) of the most recent factory reset that happened on the **mobile device**. 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). See [Factory Reset Detection](https://docs.fingerprint.com/docs/v3/smart-signals-reference#factory-reset-detection) to learn more about this Smart Signal. timestamp: type: integer format: int64 description: > This field is just another representation of the value in the `time` field. The time of the most recent factory reset that happened on the **mobile device** is expressed as Unix epoch time. ProductFactoryReset: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/FactoryReset' error: $ref: '#/components/schemas/Error' Jailbroken: type: object additionalProperties: false required: - result properties: result: type: boolean description: | iOS specific jailbreak detection. There are 2 values: * `true` - Jailbreak detected. * `false` - No signs of jailbreak or the client is not iOS. ProductJailbroken: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Jailbroken' error: $ref: '#/components/schemas/Error' Frida: type: object additionalProperties: false required: - result properties: result: type: boolean description: > [Frida](https://frida.re/docs/) 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. ProductFrida: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Frida' error: $ref: '#/components/schemas/Error' PrivacySettings: type: object additionalProperties: false required: - result properties: result: 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`. ProductPrivacySettings: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/PrivacySettings' error: $ref: '#/components/schemas/Error' VirtualMachine: type: object additionalProperties: false required: - result properties: result: type: boolean description: > `true` if the request came from a browser running inside a virtual machine (e.g. VMWare), `false` otherwise. mlScore: type: number format: double 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 ProductVirtualMachine: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/VirtualMachine' error: $ref: '#/components/schemas/Error' ProductRawDeviceAttributes: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/RawDeviceAttributes' error: $ref: '#/components/schemas/Error' HighActivity: type: object additionalProperties: false required: - result properties: result: type: boolean description: Flag indicating if the request came from a high-activity visitor. dailyRequests: type: integer format: int64 minimum: 1 description: Number of requests from the same visitor in the previous day. ProductHighActivity: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/HighActivity' error: $ref: '#/components/schemas/Error' RareDevice: type: object additionalProperties: false description: > Rare device details (present if the device is considered rare) > 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/). properties: result: 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`). percentileBucket: type: string description: > The rarity percentile bucket of the device, indicating how uncommon the device configuration is compared to all observed devices. enum: - - Flag indicating whether the request came from a mobile device with location spoofing enabled. ProductLocationSpoofing: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/LocationSpoofing' error: $ref: '#/components/schemas/Error' SuspectScore: type: object additionalProperties: false required: - result properties: result: type: integer 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/v3/suspect-score ProductSuspectScore: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/SuspectScore' error: $ref: '#/components/schemas/Error' RemoteControl: type: object deprecated: true description: | This signal is deprecated. additionalProperties: false required: - result properties: result: type: boolean description: > `true` if the request came from a machine being remotely controlled (e.g. TeamViewer), `false` otherwise. ProductRemoteControl: type: object deprecated: true description: | This product is deprecated. additionalProperties: false properties: data: $ref: '#/components/schemas/RemoteControl' error: $ref: '#/components/schemas/Error' VelocityIntervals: type: object description: > Is absent if the velocity data could not be generated for the visitor ID. additionalProperties: false required: - 5m - 1h properties: 5m: type: integer 1h: type: integer 24h: type: integer description: > The `24h` interval of `distinctIp`, `distinctLinkedId`, `distinctCountry`, `distinctIpByLinkedId` and `distinctVisitorIdByLinkedId` will be omitted if the number of `events`` for the visitor ID in the last 24 hours (`events.intervals.['24h']`) is higher than 20.000. VelocityData: type: object additionalProperties: false properties: intervals: $ref: '#/components/schemas/VelocityIntervals' Velocity: type: object description: > Sums key data points for a specific `visitorId`, `ipAddress` and `linkedId` 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 `distinctIp`, `distinctLinkedId`, `distinctCountry`, `distinctIpByLinkedId` and `distinctVisitorIdByLinkedId` will be omitted if the number of `events` for the visitor ID in the last 24 hours (`events.intervals.['24h']`) is higher than 20.000. additionalProperties: false required: - distinctIp - distinctLinkedId - distinctCountry - events - ipEvents - distinctIpByLinkedId - distinctVisitorIdByLinkedId properties: distinctIp: $ref: '#/components/schemas/VelocityData' distinctLinkedId: $ref: '#/components/schemas/VelocityData' distinctCountry: $ref: '#/components/schemas/VelocityData' events: $ref: '#/components/schemas/VelocityData' ipEvents: $ref: '#/components/schemas/VelocityData' distinctIpByLinkedId: $ref: '#/components/schemas/VelocityData' distinctVisitorIdByLinkedId: $ref: '#/components/schemas/VelocityData' ProductVelocity: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Velocity' error: $ref: '#/components/schemas/Error' DeveloperTools: type: object additionalProperties: false required: - result properties: result: type: boolean description: > `true` if the browser has DevTools open (Chrome, Firefox) or the Android/iOS device has Developer Tools enabled, `false` otherwise. ProductDeveloperTools: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/DeveloperTools' error: $ref: '#/components/schemas/Error' MitMAttack: type: object additionalProperties: false required: - result properties: result: type: boolean description: > * `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](https://docs.fingerprint.com/docs/v3/smart-signals-reference#mitm-attack-detection) to learn more about this Smart Signal. ProductMitMAttack: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/MitMAttack' error: $ref: '#/components/schemas/Error' Labels: type: array items: type: object additionalProperties: false required: - label properties: label: type: string prediction: type: boolean mlScore: type: number format: double minimum: 0 maximum: 1 description: > 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](https://fingerprint.com/support/). ProductLabels: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Labels' error: $ref: '#/components/schemas/Error' Proximity: type: object description: > Proximity ID represents a fixed geographical zone in a discrete global grid within which the device is observed. additionalProperties: false required: - id - precisionRadius - confidence properties: id: type: string description: | A stable privacy-preserving identifier for a given proximity zone. precisionRadius: 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. confidence: type: number format: float 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. * Scores closer to `1` indicate high confidence that the location is inside the mapped proximity zone. * Scores closer to `0` indicate lower confidence, suggesting the true location may fall in an adjacent zone. ProductProximity: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Proximity' error: $ref: '#/components/schemas/Error' Products: type: object description: >- Contains all information about the request identified by `requestId`, depending on the pricing plan (Pro, Pro Plus, Enterprise) additionalProperties: false properties: identification: $ref: '#/components/schemas/ProductIdentification' botd: $ref: '#/components/schemas/ProductBotd' rootApps: $ref: '#/components/schemas/ProductRootApps' emulator: $ref: '#/components/schemas/ProductEmulator' ipInfo: $ref: '#/components/schemas/ProductIPInfo' ipBlocklist: $ref: '#/components/schemas/ProductIPBlocklist' tor: $ref: '#/components/schemas/ProductTor' vpn: $ref: '#/components/schemas/ProductVPN' proxy: $ref: '#/components/schemas/ProductProxy' incognito: $ref: '#/components/schemas/ProductIncognito' tampering: $ref: '#/components/schemas/ProductTampering' clonedApp: $ref: '#/components/schemas/ProductClonedApp' factoryReset: $ref: '#/components/schemas/ProductFactoryReset' jailbroken: $ref: '#/components/schemas/ProductJailbroken' frida: $ref: '#/components/schemas/ProductFrida' privacySettings: $ref: '#/components/schemas/ProductPrivacySettings' virtualMachine: $ref: '#/components/schemas/ProductVirtualMachine' rawDeviceAttributes: $ref: '#/components/schemas/ProductRawDeviceAttributes' highActivity: $ref: '#/components/schemas/ProductHighActivity' locationSpoofing: $ref: '#/components/schemas/ProductLocationSpoofing' suspectScore: $ref: '#/components/schemas/ProductSuspectScore' remoteControl: $ref: '#/components/schemas/ProductRemoteControl' velocity: $ref: '#/components/schemas/ProductVelocity' developerTools: $ref: '#/components/schemas/ProductDeveloperTools' mitmAttack: $ref: '#/components/schemas/ProductMitMAttack' rareDevice: $ref: '#/components/schemas/ProductRareDevice' proximity: $ref: '#/components/schemas/ProductProximity' labels: $ref: '#/components/schemas/ProductLabels' EventsGetResponse: type: object description: >- Contains results from Fingerprint Identification and all active Smart Signals. additionalProperties: false required: - products properties: products: $ref: '#/components/schemas/Products' ErrorResponse: type: object additionalProperties: false required: - error properties: error: $ref: '#/components/schemas/Error' EventsUpdateRequest: type: object properties: linkedId: type: string description: LinkedID value to assign to the existing event tag: $ref: '#/components/schemas/Tag' suspect: type: boolean description: Suspect flag indicating observed suspicious or fraudulent event x-go-force-pointer: true SearchEventsResponse: type: object description: >- Contains a list of all identification events matching the specified search criteria. additionalProperties: false properties: events: type: array items: type: object description: Device intelligence results for the identification event. required: - products properties: products: $ref: '#/components/schemas/Products' paginationKey: type: string description: >- Use this value in the `pagination_key` parameter to request the next page of search results. Visit: type: object additionalProperties: false required: - requestId - browserDetails - incognito - ip - timestamp - time - url - tag - visitorFound - firstSeenAt - lastSeenAt properties: requestId: type: string description: Unique identifier of the user's request. browserDetails: $ref: '#/components/schemas/BrowserDetails' incognito: type: boolean description: Flag if user used incognito session. ip: type: string description: IP address of the requesting browser or bot. ipLocation: $ref: '#/components/schemas/DeprecatedGeolocation' linkedId: type: string description: A customer-provided id that was sent with the request. timestamp: type: integer format: int64 description: Timestamp of the event with millisecond precision in Unix time. time: type: string format: date-time x-ogen-time-format: 2006-01-02T15:04:05Z07:00 description: >- Time expressed according to ISO 8601 in UTC format, when the request from the client agent was made. We recommend to treat requests that are older than 2 minutes as malicious. Otherwise, request replay attacks are possible. url: type: string description: Page URL from which the request was sent. tag: $ref: '#/components/schemas/Tag' confidence: $ref: '#/components/schemas/IdentificationConfidence' visitorFound: type: boolean description: Attribute represents if a visitor had been identified before. firstSeenAt: $ref: '#/components/schemas/IdentificationSeenAt' lastSeenAt: $ref: '#/components/schemas/IdentificationSeenAt' components: $ref: '#/components/schemas/RawDeviceAttributes' VisitorsGetResponse: type: object description: >- Deprecated response shape for `GET /visitors/{visitor_id}`. The `visits` array currently contains at most one item. Use `GET /events/search` for multi-event history and filtering. additionalProperties: false required: - visitorId - visits properties: visitorId: type: string visits: type: array maxItems: 1 items: $ref: '#/components/schemas/Visit' lastTimestamp: deprecated: true type: integer format: int64 description: > ⚠️ Deprecated paging attribute, please use `paginationKey` instead. Timestamp of the last visit in the current page of results. paginationKey: type: string description: >- Use this value in the following request as the `paginationKey` parameter to get the next result. ErrorPlainResponse: type: object additionalProperties: false required: - error properties: error: type: string RelatedVisitor: type: object additionalProperties: false required: - visitorId properties: visitorId: type: string description: >- Visitor ID of a browser that originates from the same mobile device as the input visitor ID. RelatedVisitorsResponse: type: object additionalProperties: false required: - relatedVisitors properties: relatedVisitors: type: array items: $ref: '#/components/schemas/RelatedVisitor' WebhookRootApps: type: object additionalProperties: false properties: result: type: boolean description: > 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. WebhookEmulator: type: object additionalProperties: false properties: result: type: boolean description: | 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. WebhookIPInfo: type: object description: >- Details about the request IP address. Has separate fields for v4 and v6 IP address versions. additionalProperties: false properties: v4: $ref: '#/components/schemas/IPInfoV4' v6: $ref: '#/components/schemas/IPInfoV6' WebhookIPBlocklist: type: object additionalProperties: false properties: result: type: boolean description: > `true` if request IP address is part of any database that we use to search for known malicious actors, `false` otherwise. details: $ref: '#/components/schemas/IPBlocklistDetails' WebhookTor: type: object additionalProperties: false properties: result: type: boolean description: > `true` if the request IP address is a known tor exit node, `false` otherwise. WebhookVPN: type: object additionalProperties: false properties: result: type: boolean description: >- VPN or other anonymizing service has been used when sending the request. confidence: $ref: '#/components/schemas/VPNConfidence' mlScore: type: number format: double 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/). originTimezone: type: string description: Local timezone which is used in timezoneMismatch method. originCountry: type: string description: >- Country of the request (only for Android SDK version >= 2.4.0, ISO 3166 format or unknown). methods: $ref: '#/components/schemas/VPNMethods' WebhookProxy: type: object additionalProperties: false properties: result: type: boolean description: > IP address was used by a public proxy provider or belonged to a known recent residential proxy confidence: $ref: '#/components/schemas/ProxyConfidence' details: $ref: '#/components/schemas/ProxyDetails' mlScore: type: number format: double 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/). WebhookTampering: type: object additionalProperties: false properties: result: type: boolean description: > Indicates if an identification request from a browser or an Android SDK has been tampered with. Not supported in the iOS SDK, is always `false` for iOS requests. * `true` - If the request meets either of the following conditions: * Contains anomalous browser or device attributes that could not have been legitimately produced by the JavaScript agent or the Android SDK (see `anomalyScore`). * Originated from an anti-detect browser like Incognition (see `antiDetectBrowser`). * `false` - If the request is considered genuine or was generated by the iOS SDK. confidence: type: string enum: - low - medium - high description: | Confidence level of the tampering detection. If a tampering is not detected, confidence is "high". If it's detected, can be "low", "medium", or "high". anomalyScore: type: number format: double minimum: 0 maximum: 1 description: > A score that indicates the extent of anomalous data in the request. This field applies to requests originating from **both** browsers and Android SDKs. * Values above `0.5` indicate that the request has been tampered with. * Values below `0.5` indicate that the request is genuine. mlScore: type: number format: double minimum: 0 maximum: 1 description: > A score that indicates the models calculated probability that an event is coming from an anti detect browser. * Values above `0.8` indicate that the request is an anti detect browser based on the ml model * Values below `0.8` indicate that the request is not an anti detect browser based on the ml model antiDetectBrowser: type: boolean description: > Anti-detect browsers try to evade identification by masking or manipulating their fingerprint to imitate legitimate browser configurations. This field does not apply to requests originating from mobile SDKs. * `true` - The browser resembles a known anti-detect browser, for example, Incognition. * `false` - The browser does not resemble an anti-detect browser or the request originates from a mobile SDK. WebhookClonedApp: type: object additionalProperties: false properties: result: type: boolean description: | 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. WebhookFactoryReset: type: object additionalProperties: false properties: time: type: string format: date-time description: > Indicates the time (in UTC) of the most recent factory reset that happened on the **mobile device**. 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). See [Factory Reset Detection](https://docs.fingerprint.com/docs/v3/smart-signals-reference#factory-reset-detection) to learn more about this Smart Signal. timestamp: type: integer format: int64 description: > This field is just another representation of the value in the `time` field. The time of the most recent factory reset that happened on the **mobile device** is expressed as Unix epoch time. WebhookJailbroken: type: object additionalProperties: false properties: result: type: boolean description: | iOS specific jailbreak detection. There are 2 values: * `true` - Jailbreak detected. * `false` - No signs of jailbreak or the client is not iOS. WebhookFrida: type: object additionalProperties: false properties: result: type: boolean description: > [Frida](https://frida.re/docs/) 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. WebhookPrivacySettings: type: object additionalProperties: false properties: result: 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`. WebhookVirtualMachine: type: object additionalProperties: false properties: result: type: boolean description: > `true` if the request came from a browser running inside a virtual machine (e.g. VMWare), `false` otherwise. mlScore: type: number format: double 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 WebhookRawDeviceAttributes: type: object description: > It includes 35+ raw browser identification attributes to provide Fingerprint users with even more information than our standard visitor ID provides. This enables Fingerprint users to not have to run our open-source product in conjunction with Fingerprint Pro Plus and Enterprise to get those additional attributes. Warning: The raw signals data can change at any moment as we improve the product. We cannot guarantee the internal shape of raw device attributes to be stable, so typical semantic versioning rules do not apply here. Use this data with caution without assuming a specific structure beyond the generic type provided here. additionalProperties: $ref: '#/components/schemas/RawDeviceAttribute' WebhookHighActivity: type: object additionalProperties: false required: - result properties: result: type: boolean description: Flag indicating if the request came from a high-activity visitor. dailyRequests: type: integer format: int64 minimum: 1 description: Number of requests from the same visitor in the previous day. WebhookLocationSpoofing: type: object additionalProperties: false properties: result: type: boolean description: >- Flag indicating whether the request came from a mobile device with location spoofing enabled. WebhookSuspectScore: type: object additionalProperties: false properties: result: type: integer 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/v3/suspect-score WebhookRemoteControl: type: object deprecated: true description: | This signal is deprecated. additionalProperties: false properties: result: type: boolean description: > `true` if the request came from a machine being remotely controlled (e.g. TeamViewer), `false` otherwise. WebhookVelocity: type: object description: > Sums key data points for a specific `visitorId`, `ipAddress` and `linkedId` 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 `distinctIp`, `distinctLinkedId`, `distinctCountry`, `distinctIpByLinkedId` and `distinctVisitorIdByLinkedId` will be omitted if the number of `events` for the visitor ID in the last 24 hours (`events.intervals.['24h']`) is higher than 20.000. additionalProperties: false properties: distinctIp: $ref: '#/components/schemas/VelocityData' distinctLinkedId: $ref: '#/components/schemas/VelocityData' distinctCountry: $ref: '#/components/schemas/VelocityData' events: $ref: '#/components/schemas/VelocityData' ipEvents: $ref: '#/components/schemas/VelocityData' distinctIpByLinkedId: $ref: '#/components/schemas/VelocityData' distinctVisitorIdByLinkedId: $ref: '#/components/schemas/VelocityData' WebhookDeveloperTools: type: object additionalProperties: false properties: result: type: boolean description: > `true` if the browser has DevTools open (Chrome, Firefox) or the Android/iOS device has Developer Tools enabled, `false` otherwise. WebhookMitMAttack: type: object additionalProperties: false properties: result: type: boolean description: > * `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](https://docs.fingerprint.com/docs/v3/smart-signals-reference#mitm-attack-detection) to learn more about this Smart Signal. WebhookRareDevice: type: object additionalProperties: false properties: result: 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`). > 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/). percentileBucket: type: string description: > The rarity percentile bucket of the device, indicating how uncommon the device configuration is compared to all observed devices. enum: - - String of 20 characters that uniquely identifies the visitor's browser or mobile device. visitorFound: type: boolean description: Attribute represents if a visitor had been identified before. confidence: $ref: '#/components/schemas/IdentificationConfidence' firstSeenAt: $ref: '#/components/schemas/IdentificationSeenAt' lastSeenAt: $ref: '#/components/schemas/IdentificationSeenAt' WebhookSupplementaryIDs: type: object description: Other identities that have been established for a given Visitor. required: - standard - highRecall properties: standard: $ref: '#/components/schemas/SupplementaryID' highRecall: $ref: '#/components/schemas/SupplementaryID' WebhookProximity: type: object description: > Proximity ID represents a fixed geographical zone in a discrete global grid within which the device is observed. additionalProperties: false required: - id - precisionRadius - confidence properties: id: type: string description: | A stable privacy-preserving identifier for a given proximity zone. precisionRadius: 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. confidence: type: number format: float 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. * Scores closer to `1` indicate high confidence that the location is inside the mapped proximity zone. * Scores closer to `0` indicate lower confidence, suggesting the true location may fall in an adjacent zone. Webhook: type: object required: - requestId - url - ip - time - timestamp - sdk properties: requestId: type: string description: Unique identifier of the user's request. url: type: string description: Page URL from which the request was sent. ip: type: string description: IP address of the requesting browser or bot. environmentId: type: string description: Environment ID of the event. tag: $ref: '#/components/schemas/Tag' time: type: string format: date-time x-ogen-time-format: 2006-01-02T15:04:05.000Z07:00 description: >- Time expressed according to ISO 8601 in UTC format, when the request from the JS agent was made. We recommend to treat requests that are older than 2 minutes as malicious. Otherwise, request replay attacks are possible. timestamp: type: integer format: int64 description: Timestamp of the event with millisecond precision in Unix time. ipLocation: $ref: '#/components/schemas/DeprecatedGeolocation' linkedId: type: string description: A customer-provided id that was sent with the request. visitorId: type: string description: >- String of 20 characters that uniquely identifies the visitor's browser or mobile device. visitorFound: type: boolean description: Attribute represents if a visitor had been identified before. confidence: $ref: '#/components/schemas/IdentificationConfidence' firstSeenAt: $ref: '#/components/schemas/IdentificationSeenAt' lastSeenAt: $ref: '#/components/schemas/IdentificationSeenAt' browserDetails: $ref: '#/components/schemas/BrowserDetails' incognito: type: boolean description: Flag if user used incognito session. clientReferrer: type: string components: $ref: '#/components/schemas/RawDeviceAttributes' bot: $ref: '#/components/schemas/BotdBot' userAgent: type: string rootApps: $ref: '#/components/schemas/WebhookRootApps' emulator: $ref: '#/components/schemas/WebhookEmulator' ipInfo: $ref: '#/components/schemas/WebhookIPInfo' ipBlocklist: $ref: '#/components/schemas/WebhookIPBlocklist' tor: $ref: '#/components/schemas/WebhookTor' vpn: $ref: '#/components/schemas/WebhookVPN' proxy: $ref: '#/components/schemas/WebhookProxy' tampering: $ref: '#/components/schemas/WebhookTampering' clonedApp: $ref: '#/components/schemas/WebhookClonedApp' factoryReset: $ref: '#/components/schemas/WebhookFactoryReset' jailbroken: $ref: '#/components/schemas/WebhookJailbroken' frida: $ref: '#/components/schemas/WebhookFrida' privacySettings: $ref: '#/components/schemas/WebhookPrivacySettings' virtualMachine: $ref: '#/components/schemas/WebhookVirtualMachine' rawDeviceAttributes: $ref: '#/components/schemas/WebhookRawDeviceAttributes' highActivity: $ref: '#/components/schemas/WebhookHighActivity' locationSpoofing: $ref: '#/components/schemas/WebhookLocationSpoofing' suspectScore: $ref: '#/components/schemas/WebhookSuspectScore' remoteControl: $ref: '#/components/schemas/WebhookRemoteControl' velocity: $ref: '#/components/schemas/WebhookVelocity' developerTools: $ref: '#/components/schemas/WebhookDeveloperTools' mitmAttack: $ref: '#/components/schemas/WebhookMitMAttack' rareDevice: $ref: '#/components/schemas/WebhookRareDevice' replayed: type: boolean description: > `true` if we determined that this payload was replayed, `false` otherwise. sdk: $ref: '#/components/schemas/SDK' supplementaryIds: $ref: '#/components/schemas/WebhookSupplementaryIDs' proximity: $ref: '#/components/schemas/WebhookProximity'