> ## Documentation Index > Fetch the complete documentation index at: https://docs.fingerprint.com/llms.txt > Use this file to discover all available pages before exploring further. # Get events via search > > 🚧 Deprecation Notice > > This version of the API will **soon be deprecated** under our [API Deprecation Policy](https://dev.fingerprint.com/reference/api-deprecation-policy). The deprecation period will begin once all proxy and library integrations (both backend and frontend) are released. We will continue to provide full support for 12 months from that effective date. This notice will be updated with the **official deprecation date once it is set**. If you don’t use libraries or proxy integrations, you can use this [migration guide](https://dev.fingerprint.com/reference/migrating-from-server-api-v3-to-v4#migrating-get-eventssearch) to **start the transition to the new API today**. 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. export const DeprecatedVersion = ({currentPath}) => This version is deprecated. See the{" "} deprecation policy and use the current version instead. ; 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. ## OpenAPI ````yaml reference/fingerprint-pro-server-api.json GET /events/search openapi: 3.0.3 info: title: Server API v3 (deprecated) description: > > 🚧 Deprecation Notice > > This version of the API will **soon be deprecated** under our [API Deprecation Policy](https://dev.fingerprint.com/reference/api-deprecation-policy). The deprecation period will begin once all proxy and library integrations (both backend and frontend) are released. We will continue to provide full support for 12 months from that effective date. This notice will be updated with the **official deprecation date once it is set**. If you don’t use libraries or proxy integrations, you can use this [migration guide](https://dev.fingerprint.com/reference/migrating-from-server-api-v3-to-v4) to **start the transition to the new API today**. 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/fingerprint-pro-server-api-openapi/blob/main/LICENSE 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: [] tags: - name: Events description: > Retrieve or update information about individual events using the event's request ID. - name: Event Search description: | Search for events matching one or more filters. - name: Visitors description: | Retrieve all events of an individual visitor using their visitor ID. - name: Related Visitors description: > Find visitor IDs that originated from a different browser on the same mobile device. paths: /events/search: get: tags: - Event Search summary: Get events via search description: > > 🚧 Deprecation Notice > > This version of the API will **soon be deprecated** under our [API Deprecation Policy](https://dev.fingerprint.com/reference/api-deprecation-policy). The deprecation period will begin once all proxy and library integrations (both backend and frontend) are released. We will continue to provide full support for 12 months from that effective date. This notice will be updated with the **official deprecation date once it is set**. If you don’t use libraries or proxy integrations, you can use this [migration guide](https://dev.fingerprint.com/reference/migrating-from-server-api-v3-to-v4#migrating-get-eventssearch) to **start the transition to the new API today**. 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. operationId: searchEvents 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://dev.fingerprint.com/reference/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://dev.fingerprint.com/reference/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 description: | Sort events in reverse timestamp order. - name: suspect in: query schema: type: boolean description: > Filter events previously tagged as suspicious via the [Update API](https://dev.fingerprint.com/reference/updateevent). > 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: proxy in: query schema: type: boolean description: > 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' examples: 200-full: summary: Example search results value: events: - products: identification: data: visitorId: Ibk1527CUFmcnjLwIs4A9 requestId: 1708102555327.NLOjmg incognito: true linkedId: somelinkedId tag: {} time: '2019-05-21T16:40:13Z' timestamp: 1582299576512 url: https://www.example.com/login?hope{this{works[! ip: 61.127.217.15 ipLocation: accuracyRadius: 10 latitude: 49.982 longitude: 36.2566 postalCode: '61202' timezone: Europe/Dusseldorf city: name: Dusseldorf country: code: DE name: Germany continent: code: EU name: Europe subdivisions: - isoCode: '63' name: North Rhine-Westphalia browserDetails: browserName: Chrome browserMajorVersion: '74' browserFullVersion: 74.0.3729 os: Windows osVersion: '7' device: Other userAgent: Mozilla/5.0 (Windows NT 6.1; Win64; x64) .... confidence: score: 0.97 visitorFound: false firstSeenAt: global: '2022-03-16T11:26:45.362Z' subscription: '2022-03-16T11:31:01.101Z' lastSeenAt: global: null subscription: null replayed: false botd: data: bot: result: notDetected url: https://www.example.com/login?hope{this{works}[! ip: 61.127.217.15 time: '2019-05-21T16:40:13Z' userAgent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 YaBrowser/24.1.0.0 Safari/537.36 requestId: 1708102555327.NLOjmg rootApps: data: result: false emulator: data: result: false ipInfo: data: v4: address: 94.142.239.124 geolocation: accuracyRadius: 20 latitude: 50.05 longitude: 14.4 postalCode: 150 00 timezone: Europe/Prague city: name: Prague country: code: CZ name: Czechia continent: code: EU name: Europe subdivisions: - isoCode: '10' name: Hlavni mesto Praha asn: asn: '7922' name: COMCAST-7922 network: 73.136.0.0/13 type: isp datacenter: result: true name: DediPath v6: address: 2001:db8:3333:4444:5555:6666:7777:8888 geolocation: accuracyRadius: 5 latitude: 49.982 longitude: 36.2566 postalCode: '10112' timezone: Europe/Berlin city: name: Berlin country: code: DE name: Germany continent: code: EU name: Europe subdivisions: - isoCode: BE name: Land Berlin asn: asn: '6805' name: Telefonica Germany network: 2a02:3100::/24 type: isp datacenter: result: false name: '' ipBlocklist: data: result: false details: emailSpam: false attackSource: false tor: data: result: false vpn: data: result: false confidence: high originTimezone: Europe/Berlin originCountry: unknown methods: timezoneMismatch: false publicVPN: false auxiliaryMobile: false osMismatch: false relay: false proxy: data: result: false confidence: high details: proxyType: residential lastSeenAt: '2025-08-12T13:00:00Z' incognito: data: result: false tampering: data: result: false anomalyScore: 0.1955 antiDetectBrowser: false clonedApp: data: result: false factoryReset: data: time: '1970-01-01T00:00:00Z' timestamp: 0 jailbroken: data: result: false frida: data: result: false privacySettings: data: result: false virtualMachine: data: result: false rawDeviceAttributes: data: architecture: value: 127 audio: value: 35.73832903057337 canvas: value: Winding: true Geometry: 4dce9d6017c3e0c052a77252f29f2b1c Text: dd2474a56ff78c1de3e7a07070ba3b7d colorDepth: value: 30 colorGamut: value: p3 contrast: value: 0 cookiesEnabled: value: true cpuClass: {} fonts: value: - Arial Unicode MS - Gill Sans - Helvetica Neue - Menlo highActivity: data: result: false locationSpoofing: data: result: false velocity: data: distinctIp: intervals: 5m: 1 1h: 1 24h: 1 distinctLinkedId: {} distinctCountry: intervals: 5m: 1 1h: 2 24h: 2 events: intervals: 5m: 1 1h: 5 24h: 5 ipEvents: intervals: 5m: 1 1h: 5 24h: 5 distinctIpByLinkedId: intervals: 5m: 1 1h: 5 24h: 5 distinctVisitorIdByLinkedId: intervals: 5m: 1 1h: 5 24h: 5 developerTools: data: result: false mitmAttack: data: result: false proximity: data: id: w1aTfd4MCvl precisionRadius: 10 confidence: 0.95 paginationKey: '1655373953086' '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' examples: 400-limit-invalid: summary: Error response when no limit is supplied, or is invalid. value: error: code: RequestCannotBeParsed message: invalid limit 400-ip-address-invalid: summary: >- Error response when an invalid IP address is supplied, or is not using CIDR notation. value: error: code: RequestCannotBeParsed message: invalid ip address 400-bot-type-invalid: summary: >- Error response when an invalid bot type is specified, must be one of `good`, `bad`, `all`, or `none`. value: error: code: RequestCannotBeParsed message: invalid bot type 400-reverse-invalid: summary: Error response when the reverse parameter is invalid. value: error: code: RequestCannotBeParsed message: invalid reverse param 400-start-time-invalid: summary: Error response when an invalid start time is supplied. value: error: code: RequestCannotBeParsed message: invalid start time 400-end-time-invalid: summary: Error response when an invalid end time is supplied. value: error: code: RequestCannotBeParsed message: invalid end time 400-visitor-id-invalid: summary: Error response when an invalid visitor ID is supplied. value: error: code: RequestCannotBeParsed message: invalid visitor id 400-linked-id-invalid: summary: >- Error response when an invalid (too large) linked ID is supplied. value: error: code: RequestCannotBeParsed message: linked_id can't be greater than 256 characters long 400-pagination-key-invalid: summary: Error response when an invalid pagination key is supplied. value: error: code: RequestCannotBeParsed message: invalid pagination key '403': description: Forbidden. Access to this API is denied. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: 403-token-required: summary: Error response when the secret API key was not provided. value: error: code: TokenRequired message: secret key is required 403-token-not-found: summary: >- Error response when the provided secret API key does not exist. value: error: code: TokenNotFound message: secret key is not found 403-wrong-region: summary: >- Error response when the API region does not match the region of your Fingerprint workspace. value: error: code: WrongRegion message: wrong region components: schemas: 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. ErrorResponse: type: object additionalProperties: false required: - error properties: 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' proximity: $ref: '#/components/schemas/ProductProximity' 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' ProductBotd: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Botd' error: $ref: '#/components/schemas/Error' ProductRootApps: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/RootApps' error: $ref: '#/components/schemas/Error' ProductEmulator: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Emulator' error: $ref: '#/components/schemas/Error' ProductIPInfo: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/IPInfo' error: $ref: '#/components/schemas/Error' ProductIPBlocklist: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/IPBlocklist' error: $ref: '#/components/schemas/Error' ProductTor: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Tor' error: $ref: '#/components/schemas/Error' ProductVPN: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/VPN' error: $ref: '#/components/schemas/Error' ProductProxy: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Proxy' error: $ref: '#/components/schemas/Error' ProductIncognito: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Incognito' error: $ref: '#/components/schemas/Error' ProductTampering: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Tampering' error: $ref: '#/components/schemas/Error' ProductClonedApp: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/ClonedApp' error: $ref: '#/components/schemas/Error' ProductFactoryReset: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/FactoryReset' error: $ref: '#/components/schemas/Error' ProductJailbroken: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Jailbroken' error: $ref: '#/components/schemas/Error' ProductFrida: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Frida' error: $ref: '#/components/schemas/Error' ProductPrivacySettings: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/PrivacySettings' error: $ref: '#/components/schemas/Error' 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' ProductHighActivity: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/HighActivity' error: $ref: '#/components/schemas/Error' ProductLocationSpoofing: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/LocationSpoofing' error: $ref: '#/components/schemas/Error' ProductSuspectScore: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/SuspectScore' error: $ref: '#/components/schemas/Error' ProductRemoteControl: type: object deprecated: true description: | This product is deprecated. additionalProperties: false properties: data: $ref: '#/components/schemas/RemoteControl' error: $ref: '#/components/schemas/Error' ProductVelocity: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Velocity' error: $ref: '#/components/schemas/Error' ProductDeveloperTools: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/DeveloperTools' error: $ref: '#/components/schemas/Error' ProductMitMAttack: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/MitMAttack' error: $ref: '#/components/schemas/Error' ProductProximity: type: object additionalProperties: false properties: data: $ref: '#/components/schemas/Proximity' error: $ref: '#/components/schemas/Error' ErrorCode: type: string enum: - RequestCannotBeParsed - 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). * `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. 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://dev.fingerprint.com/reference/updateevent). 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 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.999Z07: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. 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. 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. 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' 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' 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. 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' 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' 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' Incognito: type: object additionalProperties: false required: - result properties: result: type: boolean description: > `true` if we detected incognito mode used in the browser, `false` otherwise. Tampering: type: object additionalProperties: false required: - result - anomalyScore - 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. 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. 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. 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. 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://dev.fingerprint.com/docs/smart-signals-overview#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. 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. 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. 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`. 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. 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' 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. LocationSpoofing: type: object additionalProperties: false required: - result properties: result: type: boolean description: >- Flag indicating whether the request came from a mobile device with location spoofing enabled. 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://dev.fingerprint.com/docs/suspect-score 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. 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' DeveloperTools: type: object additionalProperties: false required: - result properties: result: type: boolean description: > `true` if the browser is Chrome with DevTools open or Firefox with Developer Tools open, `false` otherwise. 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://dev.fingerprint.com/docs/smart-signals-reference#mitm-attack-detection) to learn more about this Smart Signal. 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. 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 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://dev.fingerprint.com/docs/smart-signals-overview#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.999Z07:00 subscription: type: string nullable: true format: date-time x-ogen-time-format: 2006-01-02T15:04:05.999Z07:00 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' BotdBot: type: object description: Stores bot detection result additionalProperties: false required: - result properties: result: $ref: '#/components/schemas/BotdBotResult' type: 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' 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). 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. 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 description: > Residential proxies use real user IP addresses to appear as legitimate traffic, while data center proxies are public proxies hosted in data centers 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. RawDeviceAttribute: type: object additionalProperties: false properties: value: title: value error: $ref: '#/components/schemas/RawDeviceAttributeError' VelocityData: type: object additionalProperties: false properties: intervals: $ref: '#/components/schemas/VelocityIntervals' 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 GeolocationSubdivisions: type: array items: $ref: '#/components/schemas/GeolocationSubdivision' 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". 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 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 RawDeviceAttributeError: type: object additionalProperties: false properties: name: type: string message: type: string 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. GeolocationSubdivision: type: object additionalProperties: false required: - isoCode - name properties: isoCode: type: string name: type: string securitySchemes: ApiKeyHeader: type: apiKey in: header name: Auth-API-Key ApiKeyQuery: type: apiKey in: query name: api_key ````