diff --git a/examples/errors/400_request_body_invalid.json b/examples/errors/400_request_body_invalid.json new file mode 100644 index 00000000..ce56deff --- /dev/null +++ b/examples/errors/400_request_body_invalid.json @@ -0,0 +1,6 @@ +{ + "error": { + "code": "RequestCannotBeParsed", + "message": "request body is not valid" + } +} diff --git a/examples/shared/400_error_incorrect_visitor_id.json b/examples/errors/400_visitor_id_invalid.json similarity index 100% rename from examples/shared/400_error_incorrect_visitor_id.json rename to examples/errors/400_visitor_id_invalid.json diff --git a/examples/shared/400_error_empty_visitor_id.json b/examples/errors/400_visitor_id_required.json similarity index 100% rename from examples/shared/400_error_empty_visitor_id.json rename to examples/errors/400_visitor_id_required.json diff --git a/examples/errors/403_feature_not_enabled.json b/examples/errors/403_feature_not_enabled.json new file mode 100644 index 00000000..3deac898 --- /dev/null +++ b/examples/errors/403_feature_not_enabled.json @@ -0,0 +1,6 @@ +{ + "error": { + "code": "SubscriptionNotActive", + "message": "forbidden" + } +} diff --git a/examples/shared/403_error_feature_not_enabled.json b/examples/errors/403_subscription_not_active.json similarity index 100% rename from examples/shared/403_error_feature_not_enabled.json rename to examples/errors/403_subscription_not_active.json diff --git a/examples/shared/403_error_token_not_found.json b/examples/errors/403_token_not_found.json similarity index 100% rename from examples/shared/403_error_token_not_found.json rename to examples/errors/403_token_not_found.json diff --git a/examples/get_event_403_error.json b/examples/errors/403_token_required.json similarity index 100% rename from examples/get_event_403_error.json rename to examples/errors/403_token_required.json diff --git a/examples/shared/403_error_wrong_region.json b/examples/errors/403_wrong_region.json similarity index 100% rename from examples/shared/403_error_wrong_region.json rename to examples/errors/403_wrong_region.json diff --git a/examples/get_event_404_error.json b/examples/errors/404_request_not_found.json similarity index 100% rename from examples/get_event_404_error.json rename to examples/errors/404_request_not_found.json diff --git a/examples/shared/404_error_visitor_not_found.json b/examples/errors/404_visitor_not_found.json similarity index 100% rename from examples/shared/404_error_visitor_not_found.json rename to examples/errors/404_visitor_not_found.json diff --git a/examples/errors/409_state_not_ready.json b/examples/errors/409_state_not_ready.json new file mode 100644 index 00000000..36e6dde3 --- /dev/null +++ b/examples/errors/409_state_not_ready.json @@ -0,0 +1,6 @@ +{ + "error": { + "code": "StateNotReady", + "message": "resource is not mutable yet, try again" + } +} diff --git a/examples/shared/429_error_too_many_requests.json b/examples/errors/429_too_many_requests.json similarity index 100% rename from examples/shared/429_error_too_many_requests.json rename to examples/errors/429_too_many_requests.json diff --git a/examples/get_event_200.json b/examples/get_event_200.json index e45810ad..fba76de3 100644 --- a/examples/get_event_200.json +++ b/examples/get_event_200.json @@ -173,6 +173,7 @@ "vpn": { "data": { "result": false, + "confidence": "high", "originTimezone": "Europe/Berlin", "originCountry": "unknown", "methods": { @@ -180,8 +181,7 @@ "publicVPN": false, "auxiliaryMobile": false, "osMismatch": false - }, - "confidence": "high" + } } }, "proxy": { diff --git a/examples/get_event_200_all_errors.json b/examples/get_event_200_all_errors.json index 2fe90ccb..ddc55fac 100644 --- a/examples/get_event_200_all_errors.json +++ b/examples/get_event_200_all_errors.json @@ -3,7 +3,7 @@ "identification": { "error": { "code": "Failed", - "message": "failed" + "message": "internal server error" } }, "botd": { diff --git a/examples/get_event_200_botd_too_many_requests_error.json b/examples/get_event_200_botd_too_many_requests_error.json deleted file mode 100644 index 79288281..00000000 --- a/examples/get_event_200_botd_too_many_requests_error.json +++ /dev/null @@ -1,68 +0,0 @@ -{ - "products": { - "identification": { - "data": { - "visitorId": "Ibk1527CUFmcnjLwIs4A9", - "requestId": "0KSh65EnVoB85JBmloQK", - "incognito": true, - "linkedId": "somelinkedId", - "tag": {}, - "time": "2019-05-21T16:40:13Z", - "timestamp": 1582299576512, - "url": "https://www.example.com/login", - "ip": "61.127.217.15", - "ipLocation": { - "accuracyRadius": 10, - "latitude": 49.982, - "longitude": 36.2566, - "postalCode": "61202", - "timezone": "Europe/Dusseldorf", - "city": { - "name": "Dusseldorf" - }, - "continent": { - "code": "EU", - "name": "Europe" - }, - "country": { - "code": "DE", - "name": "Germany" - }, - "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": true, - "firstSeenAt": { - "global": "2022-03-16T11:26:45.362Z", - "subscription": "2022-03-16T11:31:01.101Z" - }, - "lastSeenAt": { - "global": "2022-03-16T11:28:34.023Z", - "subscription": null - } - } - }, - "botd": { - "error": { - "code": "TooManyRequests", - "message": "too many requests" - } - } - } -} diff --git a/examples/get_event_200_identification_failed_error.json b/examples/get_event_200_identification_failed_error.json index 5b42c579..4739f36e 100644 --- a/examples/get_event_200_identification_failed_error.json +++ b/examples/get_event_200_identification_failed_error.json @@ -3,7 +3,7 @@ "identification": { "error": { "code": "Failed", - "message": "failed" + "message": "internal server error" } }, "botd": { diff --git a/examples/get_event_200_identification_too_many_requests_error.json b/examples/get_event_200_identification_too_many_requests_error.json deleted file mode 100644 index deacdcad..00000000 --- a/examples/get_event_200_identification_too_many_requests_error.json +++ /dev/null @@ -1,23 +0,0 @@ -{ - "products": { - "identification": { - "error": { - "code": "429 Too Many Requests", - "message": "too many requests" - } - }, - "botd": { - "data": { - "bot": { - "result": "bad", - "type": "headlessChrome" - }, - "url": "https://example.com/login", - "ip": "94.60.143.223", - "time": "2024-02-23T10:20:25.287Z", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/121.0.6167.57 Safari/537.36", - "requestId": "1708683625245.tuJ4nD" - } - } - } -} diff --git a/examples/get_event_200_identification_too_many_requests_error_all_fields.json b/examples/get_event_200_identification_too_many_requests_error_all_fields.json deleted file mode 100644 index 06462139..00000000 --- a/examples/get_event_200_identification_too_many_requests_error_all_fields.json +++ /dev/null @@ -1,112 +0,0 @@ -{ - "products": { - "identification": { - "error": { - "code": "429 Too Many Requests", - "message": "too many requests" - } - }, - "botd": { - "error": { - "code": "TooManyRequests", - "message": "too many requests" - } - }, - "rootApps": { - "error": { - "code": "TooManyRequests", - "message": "too many requests" - } - }, - "emulator": { - "error": { - "code": "TooManyRequests", - "message": "too many requests" - } - }, - "ipInfo": { - "error": { - "code": "TooManyRequests", - "message": "too many requests" - } - }, - "ipBlocklist": { - "error": { - "code": "TooManyRequests", - "message": "too many requests" - } - }, - "tor": { - "error": { - "code": "TooManyRequests", - "message": "too many requests" - } - }, - "vpn": { - "error": { - "code": "TooManyRequests", - "message": "too many requests" - } - }, - "proxy": { - "error": { - "code": "TooManyRequests", - "message": "too many requests" - } - }, - "incognito": { - "error": { - "code": "429 Too Many Requests", - "message": "too many requests" - } - }, - "tampering": { - "error": { - "code": "429 Too Many Requests", - "message": "too many requests" - } - }, - "clonedApp": { - "error": { - "code": "TooManyRequests", - "message": "too many requests" - } - }, - "factoryReset": { - "error": { - "code": "TooManyRequests", - "message": "too many requests" - } - }, - "jailbroken": { - "error": { - "code": "TooManyRequests", - "message": "too many requests" - } - }, - "frida": { - "error": { - "code": "TooManyRequests", - "message": "too many requests" - } - }, - "privacySettings": { - "error": { - "code": "TooManyRequests", - "message": "too many requests" - } - }, - "virtualMachine": { - "error": { - "code": "TooManyRequests", - "message": "too many requests" - } - }, - "rawDeviceAttributes": { - "error": { - "code": "429 Too Many Requests", - "message": "too many requests" - } - } - } -} diff --git a/examples/get_event_200_too_many_requests_error.json b/examples/get_event_200_too_many_requests_error.json new file mode 100644 index 00000000..138aae72 --- /dev/null +++ b/examples/get_event_200_too_many_requests_error.json @@ -0,0 +1,16 @@ +{ + "products": { + "identification": { + "error": { + "code": "429 Too Many Requests", + "message": "too many requests" + } + }, + "botd": { + "error": { + "code": "TooManyRequests", + "message": "too many requests" + } + } + } +} diff --git a/examples/get_visits_200_limit_1.json b/examples/get_visitors_200_limit_1.json similarity index 97% rename from examples/get_visits_200_limit_1.json rename to examples/get_visitors_200_limit_1.json index c5bbeedf..f6357ea5 100644 --- a/examples/get_visits_200_limit_1.json +++ b/examples/get_visitors_200_limit_1.json @@ -10,8 +10,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" }, "incognito": false, "ip": "82.118.30.68", diff --git a/examples/get_visits_200_limit_500.json b/examples/get_visitors_200_limit_500.json similarity index 96% rename from examples/get_visits_200_limit_500.json rename to examples/get_visitors_200_limit_500.json index f0451331..3e3aceb0 100644 --- a/examples/get_visits_200_limit_500.json +++ b/examples/get_visitors_200_limit_500.json @@ -10,8 +10,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" }, "incognito": false, "ip": "188.242.36.107", @@ -65,8 +64,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" }, "incognito": false, "ip": "82.118.30.62", @@ -120,8 +118,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" }, "incognito": false, "ip": "82.118.30.68", @@ -175,8 +172,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" }, "incognito": false, "ip": "82.118.30.91", @@ -230,8 +226,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" }, "incognito": false, "ip": "188.242.36.107", @@ -285,8 +280,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" }, "incognito": false, "ip": "45.86.200.137", @@ -316,8 +310,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" }, "incognito": false, "ip": "89.38.224.157", @@ -352,8 +345,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" }, "incognito": false, "ip": "188.242.36.107", @@ -386,8 +378,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" }, "incognito": false, "ip": "188.242.36.107", @@ -441,8 +432,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" }, "incognito": false, "ip": "188.242.36.107", @@ -496,8 +486,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" }, "incognito": false, "ip": "89.38.224.165", @@ -550,8 +539,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" }, "incognito": false, "ip": "89.38.224.165", @@ -604,8 +592,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" }, "incognito": false, "ip": "89.38.224.165", @@ -658,8 +645,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.64 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.64 Safari/537.36" }, "incognito": false, "ip": "89.38.224.165", @@ -712,8 +698,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36" }, "incognito": false, "ip": "89.38.224.165", @@ -766,8 +751,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36" }, "incognito": false, "ip": "89.38.224.165", @@ -820,8 +804,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36" }, "incognito": false, "ip": "89.38.224.165", @@ -874,8 +857,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36" }, "incognito": false, "ip": "89.38.224.165", @@ -928,8 +910,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36" }, "incognito": false, "ip": "89.38.224.165", @@ -982,8 +963,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36" }, "incognito": false, "ip": "217.150.54.233", @@ -1037,8 +1017,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36" }, "incognito": true, "ip": "217.150.54.233", @@ -1092,8 +1071,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36" }, "incognito": false, "ip": "217.150.54.233", @@ -1147,8 +1125,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "89.38.224.165", @@ -1201,8 +1178,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "89.38.224.165", @@ -1255,8 +1231,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "89.38.224.157", @@ -1309,8 +1284,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "89.38.224.165", @@ -1363,8 +1337,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "188.242.36.107", @@ -1418,8 +1391,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "84.247.59.113", @@ -1473,8 +1445,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "84.247.59.113", @@ -1528,8 +1499,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "84.247.59.146", @@ -1583,8 +1553,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "84.247.59.146", @@ -1638,8 +1607,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.105", @@ -1683,8 +1651,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.99", @@ -1728,8 +1695,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.99", @@ -1773,8 +1739,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.96", @@ -1818,8 +1783,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.96", @@ -1863,8 +1827,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "188.242.36.107", @@ -1918,8 +1881,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.227", @@ -1963,8 +1925,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.89", @@ -2008,8 +1969,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.111", @@ -2053,8 +2013,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.111", @@ -2098,8 +2057,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.111", @@ -2143,8 +2101,7 @@ "os": "Android", "osVersion": "6.0", "device": "Nexus 5", - "userAgent": "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36" }, "incognito": false, "ip": "45.86.200.198", @@ -2188,8 +2145,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.198", @@ -2233,8 +2189,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.206", @@ -2278,8 +2233,7 @@ "os": "Android", "osVersion": "6.0", "device": "Nexus 5", - "userAgent": "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36" }, "incognito": false, "ip": "45.86.200.204", @@ -2323,8 +2277,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.204", @@ -2368,8 +2321,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.204", @@ -2413,8 +2365,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.204", @@ -2458,8 +2409,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.172", @@ -2503,8 +2453,7 @@ "os": "Android", "osVersion": "6.0", "device": "Nexus 5", - "userAgent": "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36" }, "incognito": false, "ip": "45.86.200.210", @@ -2548,8 +2497,7 @@ "os": "Android", "osVersion": "6.0", "device": "Nexus 5", - "userAgent": "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36" }, "incognito": false, "ip": "45.86.200.210", @@ -2593,8 +2541,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.180", @@ -2638,8 +2585,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" }, "incognito": false, "ip": "45.86.200.180", @@ -2683,8 +2629,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.75 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.75 Safari/537.36" }, "incognito": false, "ip": "45.86.200.195", @@ -2728,8 +2673,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.75 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.75 Safari/537.36" }, "incognito": false, "ip": "45.86.200.179", @@ -2773,8 +2717,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.60 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.60 Safari/537.36" }, "incognito": false, "ip": "109.245.35.200", @@ -2827,8 +2770,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.60 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.60 Safari/537.36" }, "incognito": false, "ip": "109.245.35.200", @@ -2881,8 +2823,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36" }, "incognito": false, "ip": "178.223.21.183", @@ -2935,8 +2876,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36" }, "incognito": false, "ip": "87.116.165.97", @@ -2989,8 +2929,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36" }, "incognito": false, "ip": "87.116.165.97", @@ -3043,8 +2982,7 @@ "os": "Mac OS X", "osVersion": "10.15.7", "device": "Other", - "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36", - "botProbability": 0 + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36" }, "incognito": false, "ip": "87.116.165.97", diff --git a/examples/get_visitors_400_bad_request.json b/examples/get_visitors_400_bad_request.json new file mode 100644 index 00000000..c2b6e295 --- /dev/null +++ b/examples/get_visitors_400_bad_request.json @@ -0,0 +1,3 @@ +{ + "error": "bad request" +} diff --git a/examples/get_visits_403_error.json b/examples/get_visitors_403_forbidden.json similarity index 100% rename from examples/get_visits_403_error.json rename to examples/get_visitors_403_forbidden.json diff --git a/examples/get_visits_429_too_many_requests_error.json b/examples/get_visitors_429_too_many_requests.json similarity index 100% rename from examples/get_visits_429_too_many_requests_error.json rename to examples/get_visitors_429_too_many_requests.json diff --git a/examples/shared/403_error_token_required.json b/examples/shared/403_error_token_required.json deleted file mode 100644 index 544d8714..00000000 --- a/examples/shared/403_error_token_required.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "error": { - "code": "TokenRequired", - "message": "secret key is required" - } -} diff --git a/examples/update_event_400_error.json b/examples/update_event_400_error.json deleted file mode 100644 index 78568329..00000000 --- a/examples/update_event_400_error.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "error": { - "code":"RequestCannotBeParsed", - "message":"request body is not valid" - } -} diff --git a/examples/update_event_403_error.json b/examples/update_event_403_error.json deleted file mode 100644 index 544d8714..00000000 --- a/examples/update_event_403_error.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "error": { - "code": "TokenRequired", - "message": "secret key is required" - } -} diff --git a/examples/update_event_404_error.json b/examples/update_event_404_error.json deleted file mode 100644 index 389b351c..00000000 --- a/examples/update_event_404_error.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "error": { - "code": "RequestNotFound", - "message": "request id is not found" - } -} diff --git a/examples/update_event_409_error.json b/examples/update_event_409_error.json deleted file mode 100644 index 16ad29ae..00000000 --- a/examples/update_event_409_error.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "error": { - "code": "StateNotReady", - "message": "resource is not mutable yet, try again" - } -} diff --git a/examples/webhook.json b/examples/webhook.json index dea65ab9..2152b842 100644 --- a/examples/webhook.json +++ b/examples/webhook.json @@ -1,18 +1,13 @@ { "requestId": "Px6VxbRC6WBkA39yeNH3", + "url": "https://banking.example.com/signup", + "ip": "216.3.128.12", "tag": { "requestType": "signup", "yourCustomId": 45321 }, - "linkedId": "any-string", - "visitorId": "3HNey93AkBW6CRbxV6xP", - "visitorFound": true, - "timestamp": 1554910997788, "time": "2019-10-12T07:20:50.52Z", - "incognito": false, - "url": "https://banking.example.com/signup", - "clientReferrer": "https://google.com?search=banking+services", - "ip": "216.3.128.12", + "timestamp": 1554910997788, "ipLocation": { "accuracyRadius": 1, "city": { @@ -37,15 +32,9 @@ ], "timezone": "America/Chicago" }, - "browserDetails": { - "browserName": "Chrome", - "browserFullVersion": "73.0.3683.86", - "browserMajorVersion": "73", - "os": "Mac OS X", - "osVersion": "10.14.3", - "device": "Other", - "userAgent": "(Macintosh; Intel Mac OS X 10_14_3) Chrome/73.0.3683.86" - }, + "linkedId": "any-string", + "visitorId": "3HNey93AkBW6CRbxV6xP", + "visitorFound": true, "confidence": { "score": 0.97 }, @@ -57,11 +46,28 @@ "global": "2022-03-16T11:28:34.023Z", "subscription": null }, + "browserDetails": { + "browserName": "Chrome", + "browserFullVersion": "73.0.3683.86", + "browserMajorVersion": "73", + "os": "Mac OS X", + "osVersion": "10.14.3", + "device": "Other", + "userAgent": "(Macintosh; Intel Mac OS X 10_14_3) Chrome/73.0.3683.86" + }, + "incognito": false, + "clientReferrer": "https://google.com?search=banking+services", "bot": { "result": "bad", "type": "selenium" }, "userAgent": "(Macintosh; Intel Mac OS X 10_14_3) Chrome/73.0.3683.86", + "rootApps": { + "result": false + }, + "emulator": { + "result": false + }, "ipInfo": { "v4": { "address": "94.142.239.124", @@ -100,12 +106,6 @@ } } }, - "rootApps": { - "result": false - }, - "emulator": { - "result": false - }, "ipBlocklist": { "result": false, "details": { @@ -118,6 +118,7 @@ }, "vpn": { "result": false, + "confidence": "high", "originTimezone": "Europe/Berlin", "originCountry": "unknown", "methods": { @@ -125,8 +126,7 @@ "publicVPN": false, "auxiliaryMobile": false, "osMismatch": false - }, - "confidence": "high" + } }, "proxy": { "result": false diff --git a/schemas/fingerprint-related-visitors-api-readme-explorer.yaml b/schemas/fingerprint-related-visitors-api-readme-explorer.yaml index 3388b51f..baf260d7 100644 --- a/schemas/fingerprint-related-visitors-api-readme-explorer.yaml +++ b/schemas/fingerprint-related-visitors-api-readme-explorer.yaml @@ -50,15 +50,15 @@ paths: reference](https://dev.fingerprint.com/reference/related-visitors-api). parameters: - name: visitor_id - description: >- - The [visitor - ID](https://dev.fingerprint.com/docs/js-agent#visitorid) for which - you want to find the other visitor IDs that originated from the same - mobile device. in: query required: true schema: type: string + description: >- + The [visitor + ID](https://dev.fingerprint.com/reference/get-function#visitorid) + for which you want to find the other visitor IDs that originated + from the same mobile device. responses: '200': description: OK. @@ -84,18 +84,18 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorVisitor400Response' + $ref: '#/components/schemas/ErrorResponse' examples: - 400-empty-visitor-id: + 400-visitor-id-required: summary: >- Error response when the request does not include a visitor - ID + ID. value: error: code: RequestCannotBeParsed message: visitor id is required - 400-invalid-visitor-id: - summary: Error response when the visitor ID is incorrectly formatted + 400-visitor-id-invalid: + summary: Error response when the visitor ID is incorrectly formatted. value: error: code: RequestCannotBeParsed @@ -105,16 +105,14 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon403Response' + $ref: '#/components/schemas/ErrorResponse' examples: - 403-feature-not-enabled: - summary: >- - Error response when this feature is not enabled for a - subscription. + 403-token-required: + summary: Error response when the secret API key was not provided. value: error: - code: FeatureNotEnabled - message: feature not enabled + code: TokenRequired + message: secret key is required 403-token-not-found: summary: >- Error response when the provided secret API key does not @@ -123,12 +121,6 @@ paths: error: code: TokenNotFound message: secret key is not found - 403-token-required: - summary: Error response when the secret API key was not provided. - value: - error: - code: TokenRequired - message: secret key is required 403-wrong-region: summary: >- Error response when the API region is different from the @@ -137,6 +129,20 @@ paths: error: code: WrongRegion message: wrong region + 403-subscription-not-active: + summary: Error response when the subscription is not active. + value: + error: + code: FeatureNotEnabled + message: feature not enabled + 403-feature-not-enabled: + summary: >- + Error response when this feature is not enabled for a + subscription. + value: + error: + code: SubscriptionNotActive + message: forbidden '404': description: >- Not found. The visitor ID cannot be found in this application's @@ -144,7 +150,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorVisitor404Response' + $ref: '#/components/schemas/ErrorResponse' examples: 404-visitor-not-found: summary: >- @@ -159,10 +165,12 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon429Response' + $ref: '#/components/schemas/ErrorResponse' examples: - example: - summary: Too Many Requests + 429-too-many-requests: + summary: >- + Error response when the limit on the provided secret API key + requests per second has been exceeded. value: error: code: TooManyRequests @@ -181,119 +189,74 @@ components: 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. - type: string - example: Ibk1527CUFmcnjLwIs4A - required: - - visitorId RelatedVisitorsResponse: type: object additionalProperties: false + required: + - relatedVisitors properties: relatedVisitors: type: array items: $ref: '#/components/schemas/RelatedVisitor' - required: - - relatedVisitors - ErrorVisitor400Response: - type: object - additionalProperties: false - properties: - error: - type: object - additionalProperties: false - properties: - code: - type: string - description: > - Error code: * `RequestCannotBeParsed` - The visitor ID parameter - is missing or in the wrong format. - enum: - - RequestCannotBeParsed - example: RequestCannotBeParsed - message: - type: string - example: invalid visitor id - required: - - code - - message - ErrorCommon403Response: - type: object - additionalProperties: false - properties: - error: - type: object - additionalProperties: false - title: Common403ErrorResponse - properties: - code: - type: string - description: | - Error code: - * `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 - enum: - - TokenRequired - - TokenNotFound - - SubscriptionNotActive - - WrongRegion - - FeatureNotEnabled - example: TokenRequired - message: - type: string - example: secret key is required - required: - - code - - message - ErrorVisitor404Response: + ErrorCode: + type: string + enum: + - RequestCannotBeParsed + - TokenRequired + - TokenNotFound + - SubscriptionNotActive + - WrongRegion + - FeatureNotEnabled + - 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. + * `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: - error: - type: object - additionalProperties: false - title: ErrorVisitor404ResponseError - properties: - code: - type: string - description: > - Error code: * `VisitorNotFound` - The specified visitor ID was - not found. It never existed or it may have already been deleted. - enum: - - VisitorNotFound - example: VisitorNotFound - message: - type: string - example: visitor not found - required: - - code - - message - ErrorCommon429Response: + code: + $ref: '#/components/schemas/ErrorCode' + message: + type: string + ErrorResponse: type: object additionalProperties: false + required: + - error properties: error: - type: object - additionalProperties: false - properties: - code: - type: string - description: | - Error code: * `TooManyRequests` - The request is throttled. - enum: - - TooManyRequests - example: TooManyRequests - message: - type: string - example: request throttled - required: - - code - - message + $ref: '#/components/schemas/Error' diff --git a/schemas/fingerprint-server-api-compact.yaml b/schemas/fingerprint-server-api-compact.yaml index 4f428cd5..c5d9f22e 100644 --- a/schemas/fingerprint-server-api-compact.yaml +++ b/schemas/fingerprint-server-api-compact.yaml @@ -53,32 +53,34 @@ paths: parameters: - name: request_id in: path - description: >- - The unique - [identifier](https://dev.fingerprint.com/docs/js-agent#requestid) of - each identification request. required: true schema: type: string + description: >- + The unique + [identifier](https://dev.fingerprint.com/reference/get-function#requestid) + of each identification request. responses: '200': - description: OK + description: OK. content: application/json: schema: - $ref: '#/components/schemas/EventResponse' + $ref: '#/components/schemas/EventsGetResponse' '403': - description: Forbidden + description: Forbidden. Access to this API is denied. content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon403Response' + $ref: '#/components/schemas/ErrorResponse' '404': - description: Not found + description: >- + Not found. The request ID cannot be found in this application's + data. content: application/json: schema: - $ref: '#/components/schemas/ErrorEvent404Response' + $ref: '#/components/schemas/ErrorResponse' put: tags: - Fingerprint @@ -99,45 +101,47 @@ paths: parameters: - name: request_id in: path - description: >- - The unique event - [identifier](https://dev.fingerprint.com/docs/js-agent#requestid). required: true schema: type: string + description: >- + The unique event + [identifier](https://dev.fingerprint.com/reference/get-function#requestid). requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/EventUpdateRequest' + $ref: '#/components/schemas/EventsUpdateRequest' responses: '200': - description: OK + description: OK. '400': - description: Bad request + description: Bad request. The request payload is not valid. content: application/json: schema: - $ref: '#/components/schemas/ErrorUpdateEvent400Response' + $ref: '#/components/schemas/ErrorResponse' '403': - description: Forbidden + description: Forbidden. Access to this API is denied. content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon403Response' + $ref: '#/components/schemas/ErrorResponse' '404': - description: Not found + description: >- + Not found. The request ID cannot be found in this application's + data. content: application/json: schema: - $ref: '#/components/schemas/ErrorEvent404Response' + $ref: '#/components/schemas/ErrorResponse' '409': - description: Conflict + description: Conflict. The event is not mutable yet. content: application/json: schema: - $ref: '#/components/schemas/ErrorUpdateEvent409Response' + $ref: '#/components/schemas/ErrorResponse' /visitors/{visitor_id}: get: tags: @@ -160,16 +164,18 @@ paths: response is received. parameters: - name: visitor_id - description: >- - Unique [visitor - identifier](https://dev.fingerprint.com/docs/js-agent#visitorid) - issued by Fingerprint Pro. in: path required: true schema: type: string - example: uYIm7Ksp5rf00SllPhFp + description: >- + Unique [visitor + identifier](https://dev.fingerprint.com/reference/get-function#visitorid) + issued by Fingerprint Pro. - name: request_id + in: query + schema: + type: string description: > Filter visits by `requestId`. @@ -177,27 +183,29 @@ paths: Every identification request has a unique identifier associated with it called `requestId`. This identifier is returned to the client in the identification - [result](https://dev.fingerprint.com/docs/js-agent#requestid). When - you filter visits by `requestId`, only one visit will be returned. + [result](https://dev.fingerprint.com/reference/get-function#requestid). + When you filter visits by `requestId`, only one visit will be + returned. + - name: linked_id in: query schema: type: string - - name: linked_id description: > Filter visits by your custom identifier. You can use - [`linkedId`](https://dev.fingerprint.com/docs/js-agent#linkedid) to - associate identification requests with your own identifier, for + [`linkedId`](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: limit in: query schema: - type: string - required: false - - name: limit + type: integer + format: int32 + minimum: 0 description: > Limit scanned results. @@ -210,12 +218,10 @@ paths: By default, the most recent 100 visits are scanned, the maximum is 500. + - name: paginationKey in: query schema: - type: integer - format: int32 - minimum: 0 - - name: paginationKey + type: string description: > Use `paginationKey` to get the next page of results. @@ -240,34 +246,39 @@ paths: get less visits than the `limit` you specified with more available on the next page. When there are no more results available for scanning, the `paginationKey` attribute is not returned. - in: query - schema: - type: string - required: false - name: before - description: > - ⚠️ Deprecated pagination method, please use `paginationKey` instead. - Timestamp (in milliseconds since epoch) used to paginate results. 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. responses: '200': - description: OK + 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/Response' + $ref: '#/components/schemas/ErrorPlainResponse' '403': - description: Forbidden. The API Key is probably missing or incorrect. + description: Forbidden. Access to this API is denied. content: application/json: schema: - $ref: '#/components/schemas/ErrorVisits403' + $ref: '#/components/schemas/ErrorPlainResponse' '429': - description: Too Many Requests + description: Too Many Requests. The request is throttled. headers: Retry-After: description: >- @@ -280,7 +291,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/TooManyRequestsResponse' + $ref: '#/components/schemas/ErrorPlainResponse' delete: tags: - Fingerprint @@ -345,13 +356,13 @@ paths: parameters: - name: visitor_id in: path - description: >- - The [visitor - ID](https://dev.fingerprint.com/docs/js-agent#visitorid) you want to - delete. required: true schema: type: string + description: >- + The [visitor + ID](https://dev.fingerprint.com/reference/get-function#visitorid) + you want to delete. responses: '200': description: OK. The visitor ID is scheduled for deletion. @@ -362,13 +373,13 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorVisitor400Response' + $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. Access to this API is denied. content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon403Response' + $ref: '#/components/schemas/ErrorResponse' '404': description: >- Not found. The visitor ID cannot be found in this application's @@ -376,13 +387,13 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorVisitor404Response' + $ref: '#/components/schemas/ErrorResponse' '429': description: Too Many Requests. The request is throttled. content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon429Response' + $ref: '#/components/schemas/ErrorResponse' /webhook: trace: tags: @@ -391,6 +402,11 @@ paths: Fake path to describe webhook format. More information about webhooks can be found in the [documentation](https://dev.fingerprint.com/docs/webhooks) + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Webhook' responses: default: description: Dummy for the schema @@ -406,22 +422,17 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/WebhookVisit' + $ref: '#/components/schemas/Webhook' example: value: requestId: Px6VxbRC6WBkA39yeNH3 + url: https://banking.example.com/signup + ip: 216.3.128.12 tag: requestType: signup yourCustomId: 45321 - linkedId: any-string - visitorId: 3HNey93AkBW6CRbxV6xP - visitorFound: true - timestamp: 1554910997788 time: '2019-10-12T07:20:50.52Z' - incognito: false - url: https://banking.example.com/signup - clientReferrer: https://google.com?search=banking+services - ip: 216.3.128.12 + timestamp: 1554910997788 ipLocation: accuracyRadius: 1 city: @@ -439,6 +450,17 @@ paths: - isoCode: IL name: Illinois timezone: America/Chicago + linkedId: any-string + visitorId: 3HNey93AkBW6CRbxV6xP + visitorFound: true + confidence: + score: 0.97 + firstSeenAt: + global: '2022-03-16T11:26:45.362Z' + subscription: '2022-03-16T11:31:01.101Z' + lastSeenAt: + global: '2022-03-16T11:28:34.023Z' + subscription: null browserDetails: browserName: Chrome browserFullVersion: 73.0.3683.86 @@ -449,20 +471,18 @@ paths: userAgent: >- (Macintosh; Intel Mac OS X 10_14_3) Chrome/73.0.3683.86 - confidence: - score: 0.97 - firstSeenAt: - global: '2022-03-16T11:26:45.362Z' - subscription: '2022-03-16T11:31:01.101Z' - lastSeenAt: - global: '2022-03-16T11:28:34.023Z' - subscription: null + incognito: false + clientReferrer: https://google.com?search=banking+services bot: result: bad type: selenium userAgent: >- (Macintosh; Intel Mac OS X 10_14_3) Chrome/73.0.3683.86 + rootApps: + result: false + emulator: + result: false ipInfo: v4: address: 94.142.239.124 @@ -490,10 +510,6 @@ paths: datacenter: result: true name: DediPath - rootApps: - result: false - emulator: - result: false ipBlocklist: result: false details: @@ -503,6 +519,7 @@ paths: result: false vpn: result: false + confidence: high originTimezone: Europe/Berlin originCountry: unknown methods: @@ -510,7 +527,6 @@ paths: publicVPN: false auxiliaryMobile: false osMismatch: false - confidence: high proxy: result: false tampering: @@ -619,15 +635,15 @@ paths: reference](https://dev.fingerprint.com/reference/related-visitors-api). parameters: - name: visitor_id - description: >- - The [visitor - ID](https://dev.fingerprint.com/docs/js-agent#visitorid) for which - you want to find the other visitor IDs that originated from the same - mobile device. in: query required: true schema: type: string + description: >- + The [visitor + ID](https://dev.fingerprint.com/reference/get-function#visitorid) + for which you want to find the other visitor IDs that originated + from the same mobile device. responses: '200': description: OK. @@ -642,13 +658,13 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorVisitor400Response' + $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. Access to this API is denied. content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon403Response' + $ref: '#/components/schemas/ErrorResponse' '404': description: >- Not found. The visitor ID cannot be found in this application's @@ -656,13 +672,13 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorVisitor404Response' + $ref: '#/components/schemas/ErrorResponse' '429': description: Too Many Requests. The request is throttled. content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon429Response' + $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: ApiKeyHeader: @@ -677,117 +693,218 @@ components: BrowserDetails: type: object additionalProperties: false + required: + - browserName + - browserFullVersion + - browserMajorVersion + - os + - osVersion + - device + - userAgent properties: browserName: type: string - example: Chrome browserMajorVersion: type: string - example: '101' browserFullVersion: type: string - example: 101.0.4951 os: type: string - example: Windows osVersion: type: string - example: '10' device: type: string - example: Other userAgent: type: string - example: >- - Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, - like Gecko) Chrome/101.0.4951.41 Safari/537.36 - botProbability: - type: integer + GeolocationCity: + type: object + additionalProperties: false required: - - browserFullVersion - - browserMajorVersion - - browserName - - device - - os - - osVersion - - userAgent - title: BrowserDetails - Location: + - name + properties: + name: + type: string + GeolocationCountry: type: object additionalProperties: false + required: + - code + - name properties: code: type: string minLength: 2 maxLength: 2 - example: US name: type: string - example: United States + GeolocationContinent: + type: object + additionalProperties: false required: - code - name - title: Location - Subdivision: + properties: + code: + type: string + minLength: 2 + maxLength: 2 + name: + type: string + GeolocationSubdivision: type: object additionalProperties: false + required: + - isoCode + - name properties: isoCode: type: string - example: '10' name: type: string - example: Hlavni mesto Praha - Confidence: + 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://dev.fingerprint.com/docs/smart-signals-overview#ip-geolocation) + for geolocation information. additionalProperties: false properties: - score: + accuracyRadius: + type: integer + minimum: 0 description: >- - The confidence score is a floating-point number between 0 and 1 that - represents the probability of accurate identification. + 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: float + 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 - required: - - score - title: Confidence - SeenAt: + IdentificationSeenAt: type: object additionalProperties: false + required: + - global + - subscription properties: global: type: string nullable: true format: date-time - example: '2022-05-05T18:28:54.535Z' subscription: type: string nullable: true format: date-time - example: '2022-06-09T22:58:05.576Z' - required: - - global - - subscription - title: SeenAt - example: - global: '2022-05-05T18:28:54.535Z' - subscription: null - Visit: + 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' + Identification: type: object additionalProperties: false + required: + - visitorId + - requestId + - browserDetails + - incognito + - ip + - timestamp + - time + - url + - tag + - visitorFound + - firstSeenAt + - lastSeenAt properties: + visitorId: + type: string + description: >- + String of 20 characters that uniquely identifies the visitor's + browser. requestId: - description: Unique identifier of the user's identification request. type: string - example: 1654815516083.OX6kx8 + description: Unique identifier of the user's request. browserDetails: $ref: '#/components/schemas/BrowserDetails' incognito: @@ -796,283 +913,293 @@ components: ip: type: string format: ipv4 - example: 8.8.8.8 + description: IP address of the requesting browser or bot. ipLocation: - type: object - additionalProperties: false - deprecated: true - 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. - properties: - accuracyRadius: - description: >- - The IP address is likely to be within this radius (in km) of the - specified location. - type: integer - minimum: 0 - 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: - type: object - additionalProperties: false - title: DeprecatedIPLocationCity - properties: - name: - type: string - country: - $ref: '#/components/schemas/Location' - continent: - $ref: '#/components/schemas/Location' - subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: DeprecatedIPLocation + $ref: '#/components/schemas/DeprecatedGeolocation' + linkedId: + type: string + description: A customer-provided id that was sent with the request. timestamp: description: Timestamp of the event with millisecond precision in Unix time. type: integer format: int64 - example: 1654815516086 time: - title: Time - description: Time expressed according to ISO 8601 in UTC format. type: string format: date-time - example: '2022-06-09T22:58:36Z' + 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: - description: Page URL from which the identification request was sent. type: string - example: https://some.website/path?query=params + description: Page URL from which the request was sent. tag: - description: >- - A customer-provided value or an object that was sent with - identification request. - type: object - additionalProperties: true - linkedId: - description: A customer-provided id that was sent with identification request. - type: string - example: someID + $ref: '#/components/schemas/Tag' confidence: - $ref: '#/components/schemas/Confidence' + $ref: '#/components/schemas/IdentificationConfidence' visitorFound: - description: Attribute represents if a visitor had been identified before. type: boolean + description: Attribute represents if a visitor had been identified before. firstSeenAt: - $ref: '#/components/schemas/SeenAt' + $ref: '#/components/schemas/IdentificationSeenAt' lastSeenAt: - $ref: '#/components/schemas/SeenAt' + $ref: '#/components/schemas/IdentificationSeenAt' + components: + $ref: '#/components/schemas/RawDeviceAttributes' + ErrorCode: + type: string + enum: + - RequestCannotBeParsed + - TokenRequired + - TokenNotFound + - SubscriptionNotActive + - WrongRegion + - FeatureNotEnabled + - 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. + * `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: - - browserDetails - - firstSeenAt - - incognito - - ip - - lastSeenAt - - requestId - - time - - timestamp - - url - - visitorFound - title: Visit - IdentificationError: - type: object - additionalProperties: false + - code + - message properties: code: - type: string - description: | - Error code: - * `429 Too Many Requests` - the limit on secret API key requests per second has been exceeded - * `Failed` - internal server error - enum: - - 429 Too Many Requests - - Failed - example: 429 Too Many Requests + $ref: '#/components/schemas/ErrorCode' message: type: string - example: too many requests - required: - - code - - message - BotdDetectionResult: + 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: - type: string - 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 - enum: - - notDetected - - good - - bad - example: bad + $ref: '#/components/schemas/BotdBotResult' type: type: string - example: selenium - required: - - result - BotdResult: + Botd: type: object - additionalProperties: false 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 format: ipv4 - example: 8.8.8.8 description: IP address of the requesting browser or bot. time: - title: Time + type: string + format: date-time 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 - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - url: - description: Page URL from which identification request was sent. - type: string - example: https://example.com/login + malicious. Otherwise, request replay attacks are possible. userAgent: type: string - example: >- - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 - (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 requestId: type: string - example: 1681392853693.lRiBBD - linkedId: - type: string - example: Automatic tests bot - bot: - $ref: '#/components/schemas/BotdDetectionResult' + 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: - - bot - - url - - ip - - time - - userAgent - - requestId - ProductError: + - 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: - code: - type: string - description: | - Error code: - * `TooManyRequests` - the limit on secret API key requests per second has been exceeded - * `Failed` - internal server error - enum: - - TooManyRequests - - Failed - example: TooManyRequests - message: - type: string - example: too many requests + data: + $ref: '#/components/schemas/RootApps' + error: + $ref: '#/components/schemas/Error' + Emulator: + type: object + additionalProperties: false required: - - code - - message - IPLocation: + - 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. - type: integer - minimum: 0 - example: 1000 latitude: type: number format: double minimum: -90 maximum: 90 - example: 37.75 longitude: type: number format: double minimum: -180 maximum: 180 - example: -97.82 postalCode: type: string - example: 130 00 timezone: type: string format: timezone - example: America/Chicago city: - type: object - additionalProperties: false - title: IPLocationCity - properties: - name: - type: string - example: Prague + $ref: '#/components/schemas/GeolocationCity' country: - $ref: '#/components/schemas/Location' + $ref: '#/components/schemas/GeolocationCountry' continent: - $ref: '#/components/schemas/Location' + $ref: '#/components/schemas/GeolocationContinent' subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: IPLocation - ASN: + $ref: '#/components/schemas/GeolocationSubdivisions' + IPInfoASN: type: object additionalProperties: false + required: + - asn + - name + - network properties: asn: type: string - example: '7922' - network: - type: string - example: 73.136.0.0/13 name: type: string - example: COMCAST-7922 - required: - - asn - - network - title: ASN - DataCenter: + network: + type: string + IPInfoDataCenter: type: object additionalProperties: false + required: + - result + - name properties: result: type: boolean name: type: string - example: DediPath + IPInfoV4: + type: object + additionalProperties: false required: - - result - title: DataCenter - IpInfoResult: + - 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 @@ -1080,362 +1207,414 @@ components: additionalProperties: false properties: v4: - type: object - additionalProperties: false - properties: - address: - type: string - format: ipv4 - example: 94.142.239.124 - geolocation: - $ref: '#/components/schemas/IPLocation' - asn: - $ref: '#/components/schemas/ASN' - datacenter: - $ref: '#/components/schemas/DataCenter' - required: - - address - - geolocation + $ref: '#/components/schemas/IPInfoV4' v6: - type: object - additionalProperties: false - properties: - address: - type: string - format: ipv6 - example: 2001:0db8:85a3:0000:0000:8a2e:0370:7334 - geolocation: - $ref: '#/components/schemas/IPLocation' - asn: - $ref: '#/components/schemas/ASN' - datacenter: - $ref: '#/components/schemas/DataCenter' - required: - - address - - geolocation - IncognitoResult: + $ref: '#/components/schemas/IPInfoV6' + ProductIPInfo: type: object additionalProperties: false properties: - result: - type: boolean - description: > - `true` if we detected incognito mode used in the browser, `false` - otherwise. - example: false - required: - - result - RootAppsResult: + data: + $ref: '#/components/schemas/IPInfo' + error: + $ref: '#/components/schemas/Error' + IPBlocklistDetails: 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. - example: false required: - - result - EmulatorResult: - type: object - additionalProperties: false + - emailSpam + - attackSource properties: - result: + emailSpam: 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. - example: false - required: - - result - ClonedAppResult: - type: object - additionalProperties: false - properties: - result: + description: IP address was part of a known email spam attack (SMTP). + attackSource: 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. - example: false - required: - - result - FactoryResetResult: + description: IP address was part of a known network attack (SSH/HTTPS). + IPBlocklist: type: object additionalProperties: false - properties: - 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. - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - timestamp: - 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. - type: integer - format: int64 - example: 1654815517198 required: - - time - - timestamp - JailbrokenResult: - type: object - additionalProperties: false + - result + - details 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. - example: false - required: - - result - FridaResult: + `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: - 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. - example: false - required: - - result - IpBlockListResult: + data: + $ref: '#/components/schemas/IPBlocklist' + error: + $ref: '#/components/schemas/Error' + Tor: 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. - example: false - details: - type: object - additionalProperties: false - properties: - emailSpam: - type: boolean - description: IP address was part of a known email spam attack (SMTP). - example: false - attackSource: - type: boolean - description: IP address was part of a known network attack (SSH/HTTPS). - example: false - required: - - emailSpam - - attackSource required: - result - - details - TorResult: - type: object - additionalProperties: false properties: result: type: boolean description: > `true` if the request IP address is a known tor exit node, `false` otherwise. - example: false - required: - - result - PrivacySettingsResult: + ProductTor: 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`. - example: false - required: - - result - VirtualMachineResult: + 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 properties: - result: + timezoneMismatch: type: boolean - description: > - `true` if the request came from a browser running inside a virtual - machine (e.g. VMWare), `false` otherwise. - example: false - required: - - result - VpnResult: + 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. + 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. - example: false + confidence: + $ref: '#/components/schemas/VPNConfidence' originTimezone: type: string description: Local timezone which is used in timezoneMismatch method. - example: Europe/Berlin originCountry: type: string description: >- Country of the request (only for Android SDK version >= 2.4.0, ISO 3166 format or unknown). - example: unknown methods: - type: object - additionalProperties: false - properties: - timezoneMismatch: - type: boolean - description: >- - The browser timezone doesn't match the timezone inferred from - the request IP address. - example: false - publicVPN: - type: boolean - description: >- - Request IP address is owned and used by a public VPN service - provider. - example: false - 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. - example: false - osMismatch: - type: boolean - description: >- - The browser runs on a different operating system than the - operating system inferred from the request network signature. - example: false - required: - - timezoneMismatch - - publicVPN - - auxiliaryMobile - - osMismatch - confidence: - 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. - example: low - required: - - result - - originTimezone - - methods - - confidence - ProxyResult: + $ref: '#/components/schemas/VPNMethods' + ProductVPN: + type: object + additionalProperties: false + properties: + data: + $ref: '#/components/schemas/VPN' + error: + $ref: '#/components/schemas/Error' + Proxy: type: object additionalProperties: false + required: + - result properties: result: type: boolean description: > `true` if the request IP address is used by a public proxy provider, `false` otherwise. - example: false - required: - - result - TamperingResult: + 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: >- - Flag indicating browser tampering was detected. This happens when - either of these conditions is true: - * There are inconsistencies in the browser configuration that cross our internal tampering thresholds (indicated by `anomalyScore`). - * The browser signature resembles one of "anti-detect" browsers specifically designed to evade identification and fingerprinting, for example, Incognition (indicated by `antiDetectBrowser`). - example: false + 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 + - anomalyScore + - antiDetectBrowser + properties: + result: + type: boolean + description: > + Flag indicating browser tampering was detected. This happens when + either of these conditions is true: + * There are inconsistencies in the browser configuration that cross our internal tampering thresholds (indicated by `anomalyScore`). + * The browser signature resembles one of "anti-detect" browsers specifically designed to evade identification and fingerprinting, for example, Incognition (indicated by `antiDetectBrowser`). anomalyScore: type: number - description: >- - Confidence score (`0.0 - 1.0`) for tampering detection. Values above - `0.5` indicate that there was a tampering attempt. Values below - `0.5` indicate genuine browsers. - example: 0 + format: double minimum: 0 maximum: 1 + description: | + Confidence score (`0.0 - 1.0`) for tampering detection: + * Values above `0.5` indicate that there was a tampering attempt. + * Values below `0.5` indicate genuine browsers. antiDetectBrowser: type: boolean description: >- Is `true` if the identified browser resembles one of "anti-detect" - browsers, for example, Incognition. Anti-detect browsers try to + browsers, for example, Incognition. Anti-detect browsers try to evade identification by masking or manipulating their fingerprint to imitate legitimate browser configurations. - example: false + ProductTampering: + type: object + additionalProperties: false + properties: + data: + $ref: '#/components/schemas/Tampering' + error: + $ref: '#/components/schemas/Error' + ClonedApp: + type: object + additionalProperties: false required: - result - - anomalyScore - - antiDetectBrowser - HighActivityResult: + 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://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. + 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: >- - Flag indicating whether the request came from a high activity - visitor. - example: false - dailyRequests: - type: number - description: Number of requests from the same visitor in the previous day. - example: 10 - minimum: 1 + 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. + 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 - LocationSpoofingResult: + 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' + 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. - example: false - required: - - result - SuspectScoreResult: + 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 @@ -1446,66 +1625,47 @@ components: 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 - example: 0 - required: - - result - RawDeviceAttributesResult: + ProductSuspectScore: 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: - type: object - properties: - error: - properties: - name: - title: error.name - type: string - message: - title: error.message - type: string - required: - - name - - message - title: error - type: object - value: - title: value - RemoteControlResult: + additionalProperties: false + properties: + data: + $ref: '#/components/schemas/SuspectScore' + error: + $ref: '#/components/schemas/Error' + RemoteControl: type: object 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. - example: false - required: - - result - VelocityIntervalResult: + ProductRemoteControl: + type: object + 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 - example: 1 1h: type: integer - example: 1 24h: type: integer description: > @@ -1514,17 +1674,13 @@ components: `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. - example: 1 - required: - - 5m - - 1h - VelocityIntervals: + VelocityData: type: object additionalProperties: false properties: intervals: - $ref: '#/components/schemas/VelocityIntervalResult' - VelocityResult: + $ref: '#/components/schemas/VelocityIntervals' + Velocity: type: object description: > Sums key data points for a specific `visitorId`, `ipAddress` and @@ -1533,15 +1689,16 @@ components: intervals: 5 minutes, 1 hour, and 24 hours as follows: - - Number of identification events associated with the visitor ID. + - Number of distinct IP addresses associated to the visitor ID. - Number of distinct linked IDs associated with the visitor ID. - - Number of distinct IP addresses associated to the visitor ID. - - Number of distinct countries associated with the visitor ID. - - Number of events associated for the detected IP address. + - 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. @@ -1559,42 +1716,57 @@ components: hours (`events.intervals.['24h']`) is higher than 20.000. additionalProperties: false - properties: - events: - $ref: '#/components/schemas/VelocityIntervals' - distinctLinkedId: - $ref: '#/components/schemas/VelocityIntervals' - distinctIp: - $ref: '#/components/schemas/VelocityIntervals' - distinctCountry: - $ref: '#/components/schemas/VelocityIntervals' - ipEvents: - $ref: '#/components/schemas/VelocityIntervals' - distinctIpByLinkedId: - $ref: '#/components/schemas/VelocityIntervals' - distinctVisitorIdByLinkedId: - $ref: '#/components/schemas/VelocityIntervals' required: - - events - - distinctLinkedId - distinctIp + - distinctLinkedId - distinctCountry + - events - ipEvents - distinctIpByLinkedId - distinctVisitorIdByLinkedId - DeveloperToolsResult: + 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 is Chrome with DevTools open or Firefox with Developer Tools open, `false` otherwise. - example: false - required: - - result - ProductsResponse: + ProductDeveloperTools: + type: object + additionalProperties: false + properties: + data: + $ref: '#/components/schemas/DeveloperTools' + error: + $ref: '#/components/schemas/Error' + Products: type: object description: >- Contains all information about the request identified by `requestId`, @@ -1602,897 +1774,614 @@ components: additionalProperties: false properties: identification: - type: object - additionalProperties: false - title: ProductsResponseIdentification - properties: - data: - title: ProductsResponseIdentificationData - type: object - properties: - requestId: - description: Unique identifier of the user's identification request. - type: string - example: 1654815516083.OX6kx8 - browserDetails: - $ref: '#/components/schemas/BrowserDetails' - incognito: - description: Flag if user used incognito session. - type: boolean - ip: - type: string - format: ipv4 - example: 8.8.8.8 - ipLocation: - type: object - additionalProperties: false - deprecated: true - 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. - properties: - accuracyRadius: - description: >- - The IP address is likely to be within this radius (in - km) of the specified location. - type: integer - minimum: 0 - 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: - type: object - additionalProperties: false - title: DeprecatedIPLocationCity - properties: - name: - type: string - country: - $ref: '#/components/schemas/Location' - continent: - $ref: '#/components/schemas/Location' - subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: DeprecatedIPLocation - timestamp: - description: >- - Timestamp of the event with millisecond precision in Unix - time. - type: integer - format: int64 - example: 1654815516086 - time: - title: Time - description: Time expressed according to ISO 8601 in UTC format. - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - url: - description: Page URL from which the identification request was sent. - type: string - example: https://some.website/path?query=params - tag: - description: >- - A customer-provided value or an object that was sent with - identification request. - type: object - additionalProperties: true - linkedId: - description: >- - A customer-provided id that was sent with identification - request. - type: string - example: someID - confidence: - $ref: '#/components/schemas/Confidence' - visitorFound: - description: >- - Attribute represents if a visitor had been identified - before. - type: boolean - firstSeenAt: - $ref: '#/components/schemas/SeenAt' - lastSeenAt: - $ref: '#/components/schemas/SeenAt' - visitorId: - type: string - description: > - String of 20 characters that uniquely identifies the - visitor's browser. - example: - - Ibk1527CUFmcnjLwIs4A - additionalProperties: false - required: - - browserDetails - - firstSeenAt - - incognito - - ip - - lastSeenAt - - requestId - - time - - timestamp - - url - - visitorFound - - visitorId - - tag - error: - $ref: '#/components/schemas/IdentificationError' + $ref: '#/components/schemas/ProductIdentification' botd: - title: ProductsResponseBotd - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/BotdResult' - error: - $ref: '#/components/schemas/ProductError' - ipInfo: - title: SignalResponseIpInfo - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/IpInfoResult' - error: - $ref: '#/components/schemas/ProductError' - incognito: - title: SignalResponseIncognito - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/IncognitoResult' - error: - $ref: '#/components/schemas/IdentificationError' + $ref: '#/components/schemas/ProductBotd' rootApps: - title: SignalResponseRootApps - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/RootAppsResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductRootApps' emulator: - title: SignalResponseEmulator - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/EmulatorResult' - error: - $ref: '#/components/schemas/ProductError' + $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: - title: SignalResponseClonedApp - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/ClonedAppResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductClonedApp' factoryReset: - title: SignalResponseFactoryReset - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/FactoryResetResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductFactoryReset' jailbroken: - title: SignalResponseJailbroken - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/JailbrokenResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductJailbroken' frida: - title: SignalResponseFrida - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/FridaResult' - error: - $ref: '#/components/schemas/ProductError' - ipBlocklist: - title: SignalResponseIpBlocklist - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/IpBlockListResult' - error: - $ref: '#/components/schemas/ProductError' - tor: - title: SignalResponseTor - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/TorResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductFrida' privacySettings: - title: SignalResponsePrivacySettings - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/PrivacySettingsResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductPrivacySettings' virtualMachine: - title: SignalResponseVirtualMachine - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/VirtualMachineResult' - error: - $ref: '#/components/schemas/ProductError' - vpn: - title: SignalResponseVpn - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/VpnResult' - error: - $ref: '#/components/schemas/ProductError' - proxy: - title: SignalResponseProxy - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/ProxyResult' - error: - $ref: '#/components/schemas/ProductError' - tampering: - title: SignalResponseTampering - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/TamperingResult' - error: - $ref: '#/components/schemas/IdentificationError' + $ref: '#/components/schemas/ProductVirtualMachine' + rawDeviceAttributes: + $ref: '#/components/schemas/ProductRawDeviceAttributes' highActivity: - title: SignalResponseHighActivity - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/HighActivityResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductHighActivity' locationSpoofing: - title: SignalResponseLocationSpoofing - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/LocationSpoofingResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductLocationSpoofing' suspectScore: - title: SignalResponseSuspectScore - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/SuspectScoreResult' - error: - $ref: '#/components/schemas/ProductError' - rawDeviceAttributes: - title: SignalResponseRawDeviceAttributes - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/RawDeviceAttributesResult' - error: - $ref: '#/components/schemas/IdentificationError' + $ref: '#/components/schemas/ProductSuspectScore' remoteControl: - title: SignalResponseRemoteControl - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/RemoteControlResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductRemoteControl' velocity: - title: SignalResponseVelocity - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/VelocityResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductVelocity' developerTools: - title: SignalResponseDeveloperTools - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/DeveloperToolsResult' - error: - $ref: '#/components/schemas/ProductError' - EventResponse: + $ref: '#/components/schemas/ProductDeveloperTools' + EventsGetResponse: + type: object description: >- Contains results from all activated products - Fingerprint Pro, Bot Detection, and others. - type: object additionalProperties: false - properties: - products: - $ref: '#/components/schemas/ProductsResponse' - error: - $ref: '#/components/schemas/ProductError' required: - products - ErrorCommon403Response: - type: object - additionalProperties: false - properties: - error: - type: object - additionalProperties: false - title: Common403ErrorResponse - properties: - code: - type: string - description: | - Error code: - * `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 - enum: - - TokenRequired - - TokenNotFound - - SubscriptionNotActive - - WrongRegion - - FeatureNotEnabled - example: TokenRequired - message: - type: string - example: secret key is required - required: - - code - - message - ErrorEvent404Response: + properties: + products: + $ref: '#/components/schemas/Products' + ErrorResponse: type: object additionalProperties: false + required: + - error properties: error: - type: object - additionalProperties: false - title: ErrorEvent404ResponseError - properties: - code: - type: string - description: | - Error code: - * `RequestNotFound` - The specified request ID was not found. It never existed, expired, or it has been deleted. - enum: - - RequestNotFound - example: RequestNotFound - message: - type: string - example: request id is not found - required: - - code - - message - EventUpdateRequest: + $ref: '#/components/schemas/Error' + EventsUpdateRequest: type: object properties: linkedId: type: string description: LinkedID value to assign to the existing event tag: - type: object - description: >- - Full `tag` value to be set to the existing event. Replaces any - existing `tag` payload completely. + $ref: '#/components/schemas/Tag' suspect: type: boolean description: Suspect flag indicating observed suspicious or fraudulent event - ErrorUpdateEvent400Response: - type: object - additionalProperties: false - properties: - error: - type: object - additionalProperties: false - title: ErrorUpdateEvent400ResponseError - properties: - code: - type: string - description: > - Error code: * `RequestCannotBeParsed` - the JSON content of the - request contains some errors that prevented us from parsing it - (wrong type/surpassed limits) * `Failed` - the event is more - than 10 days old and cannot be updated - enum: - - RequestCannotBeParsed - - Failed - example: RequestCannotBeParsed - message: - type: string - description: Details about the underlying issue with the input payload - example: suspect flag must be a boolean - required: - - code - - message - ErrorUpdateEvent409Response: + Visit: type: object additionalProperties: false + required: + - requestId + - browserDetails + - incognito + - ip + - timestamp + - time + - url + - tag + - visitorFound + - firstSeenAt + - lastSeenAt properties: - error: - type: object - additionalProperties: false - title: ErrorUpdateEvent409ResponseError - properties: - code: - type: string - description: > - Error code: * `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. - enum: - - StateNotReady - example: StateNotReady - message: - type: string - example: resource is not mutable yet, try again - required: - - code - - message - Response: + 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 + format: ipv4 + 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 + 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: >- + Pagination-related fields `lastTimestamp` and `paginationKey` are + included if you use a pagination parameter like `limit` or `before` and + there is more data available on the next page. additionalProperties: false + required: + - visitorId + - visits properties: visitorId: type: string visits: type: array items: - title: ResponseVisits - type: object - properties: - requestId: - description: Unique identifier of the user's identification request. - type: string - example: 1654815516083.OX6kx8 - browserDetails: - $ref: '#/components/schemas/BrowserDetails' - incognito: - description: Flag if user used incognito session. - type: boolean - ip: - type: string - format: ipv4 - example: 8.8.8.8 - ipLocation: - type: object - additionalProperties: false - deprecated: true - 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. - properties: - accuracyRadius: - description: >- - The IP address is likely to be within this radius (in km) - of the specified location. - type: integer - minimum: 0 - 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: - type: object - additionalProperties: false - title: DeprecatedIPLocationCity - properties: - name: - type: string - country: - $ref: '#/components/schemas/Location' - continent: - $ref: '#/components/schemas/Location' - subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: DeprecatedIPLocation - timestamp: - description: >- - Timestamp of the event with millisecond precision in Unix - time. - type: integer - format: int64 - example: 1654815516086 - time: - title: Time - description: Time expressed according to ISO 8601 in UTC format. - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - url: - description: Page URL from which the identification request was sent. - type: string - example: https://some.website/path?query=params - tag: - description: >- - A customer-provided value or an object that was sent with - identification request. - type: object - additionalProperties: true - linkedId: - description: >- - A customer-provided id that was sent with identification - request. - type: string - example: someID - confidence: - $ref: '#/components/schemas/Confidence' - visitorFound: - description: Attribute represents if a visitor had been identified before. - type: boolean - firstSeenAt: - $ref: '#/components/schemas/SeenAt' - lastSeenAt: - $ref: '#/components/schemas/SeenAt' - additionalProperties: false - required: - - browserDetails - - firstSeenAt - - incognito - - ip - - lastSeenAt - - requestId - - time - - timestamp - - url - - visitorFound - - tag + $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. - type: integer - format: int64 - example: 1654815517198 paginationKey: + type: string description: >- Request ID of the last visit in the current page of results. Use this value in the following request as the `paginationKey` parameter to get the next page of results. - type: string - example: 1654815517198.azN4IZ + ErrorPlainResponse: + type: object + additionalProperties: false required: - - visitorId - - visits - title: PaginatedResponse + - error + properties: + error: + type: string + 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: >- - Fields `lastTimestamp` and `paginationKey` added when `limit` or - `before` parameter provided and there is more data to show - ErrorVisits403: + 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: - error: + 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' + originTimezone: type: string - description: Error text. - example: Forbidden (HTTP 403) - required: - - error - TooManyRequestsResponse: + 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: - error: + result: + type: boolean + description: > + `true` if the request IP address is used by a public proxy provider, + `false` otherwise. + WebhookTampering: + type: object + additionalProperties: false + properties: + result: + type: boolean + description: > + Flag indicating browser tampering was detected. This happens when + either of these conditions is true: + * There are inconsistencies in the browser configuration that cross our internal tampering thresholds (indicated by `anomalyScore`). + * The browser signature resembles one of "anti-detect" browsers specifically designed to evade identification and fingerprinting, for example, Incognition (indicated by `antiDetectBrowser`). + anomalyScore: + type: number + format: double + minimum: 0 + maximum: 1 + description: | + Confidence score (`0.0 - 1.0`) for tampering detection: + * Values above `0.5` indicate that there was a tampering attempt + * Values below `0.5` indicate genuine browsers. + antiDetectBrowser: + type: boolean + description: >- + Is `true` if the identified browser resembles one of "anti-detect" + browsers, for example, Incognition. Anti-detect browsers try to + evade identification by masking or manipulating their fingerprint to + imitate legitimate browser configurations. + 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 - description: Error text. - example: request throttled + 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. + 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. + 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: - - error - ErrorVisitor400Response: + - 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: - error: - type: object - additionalProperties: false - properties: - code: - type: string - description: > - Error code: * `RequestCannotBeParsed` - The visitor ID parameter - is missing or in the wrong format. - enum: - - RequestCannotBeParsed - example: RequestCannotBeParsed - message: - type: string - example: invalid visitor id - required: - - code - - message - ErrorVisitor404Response: + result: + type: boolean + description: >- + Flag indicating whether the request came from a mobile device with + location spoofing enabled. + WebhookSuspectScore: type: object additionalProperties: false properties: - error: - type: object - additionalProperties: false - title: ErrorVisitor404ResponseError - properties: - code: - type: string - description: > - Error code: * `VisitorNotFound` - The specified visitor ID was - not found. It never existed or it may have already been deleted. - enum: - - VisitorNotFound - example: VisitorNotFound - message: - type: string - example: visitor not found - required: - - code - - message - ErrorCommon429Response: + 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 + WebhookRemoteControl: type: object additionalProperties: false properties: - error: - type: object - additionalProperties: false - properties: - code: - type: string - description: | - Error code: * `TooManyRequests` - The request is throttled. - enum: - - TooManyRequests - example: TooManyRequests - message: - type: string - example: request throttled - required: - - code - - message - WebhookVisit: + 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 is Chrome with DevTools open or Firefox with + Developer Tools open, `false` otherwise. + Webhook: + type: object + required: + - requestId + - url + - ip + - time + - timestamp 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 + format: ipv4 + description: IP address of the requesting browser or bot. + tag: + $ref: '#/components/schemas/Tag' + time: + type: string + format: date-time + 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 - example: 3HNey93AkBW6CRbxV6xP + description: >- + String of 20 characters that uniquely identifies the visitor's + browser. + 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 - example: https://google.com?search=banking+services + components: + $ref: '#/components/schemas/RawDeviceAttributes' + bot: + $ref: '#/components/schemas/BotdBot' userAgent: type: string - example: >- - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 - (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 - bot: - $ref: '#/components/schemas/BotdDetectionResult' - ipInfo: - $ref: '#/components/schemas/IpInfoResult' - incognito: - description: Flag if user used incognito session. - type: boolean rootApps: - $ref: '#/components/schemas/RootAppsResult' + $ref: '#/components/schemas/WebhookRootApps' emulator: - $ref: '#/components/schemas/EmulatorResult' + $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/ClonedAppResult' + $ref: '#/components/schemas/WebhookClonedApp' factoryReset: - $ref: '#/components/schemas/FactoryResetResult' + $ref: '#/components/schemas/WebhookFactoryReset' jailbroken: - $ref: '#/components/schemas/JailbrokenResult' + $ref: '#/components/schemas/WebhookJailbroken' frida: - $ref: '#/components/schemas/FridaResult' - ipBlocklist: - $ref: '#/components/schemas/IpBlockListResult' - tor: - $ref: '#/components/schemas/TorResult' + $ref: '#/components/schemas/WebhookFrida' privacySettings: - $ref: '#/components/schemas/PrivacySettingsResult' + $ref: '#/components/schemas/WebhookPrivacySettings' virtualMachine: - $ref: '#/components/schemas/VirtualMachineResult' - vpn: - $ref: '#/components/schemas/VpnResult' - proxy: - $ref: '#/components/schemas/ProxyResult' - tampering: - $ref: '#/components/schemas/TamperingResult' + $ref: '#/components/schemas/WebhookVirtualMachine' rawDeviceAttributes: - $ref: '#/components/schemas/RawDeviceAttributesResult' + $ref: '#/components/schemas/WebhookRawDeviceAttributes' highActivity: - $ref: '#/components/schemas/HighActivityResult' + $ref: '#/components/schemas/WebhookHighActivity' locationSpoofing: - $ref: '#/components/schemas/LocationSpoofingResult' + $ref: '#/components/schemas/WebhookLocationSpoofing' suspectScore: - $ref: '#/components/schemas/SuspectScoreResult' + $ref: '#/components/schemas/WebhookSuspectScore' remoteControl: - $ref: '#/components/schemas/RemoteControlResult' + $ref: '#/components/schemas/WebhookRemoteControl' velocity: - $ref: '#/components/schemas/VelocityResult' + $ref: '#/components/schemas/WebhookVelocity' developerTools: - $ref: '#/components/schemas/DeveloperToolsResult' - requestId: - description: Unique identifier of the user's identification request. - type: string - example: 1654815516083.OX6kx8 - browserDetails: - $ref: '#/components/schemas/BrowserDetails' - ip: - type: string - format: ipv4 - example: 8.8.8.8 - ipLocation: - type: object - additionalProperties: false - deprecated: true - 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. - properties: - accuracyRadius: - description: >- - The IP address is likely to be within this radius (in km) of the - specified location. - type: integer - minimum: 0 - 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: - type: object - additionalProperties: false - title: DeprecatedIPLocationCity - properties: - name: - type: string - country: - $ref: '#/components/schemas/Location' - continent: - $ref: '#/components/schemas/Location' - subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: DeprecatedIPLocation - timestamp: - description: Timestamp of the event with millisecond precision in Unix time. - type: integer - format: int64 - example: 1654815516086 - time: - title: Time - description: Time expressed according to ISO 8601 in UTC format. - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - url: - description: Page URL from which the identification request was sent. - type: string - example: https://some.website/path?query=params - tag: - description: >- - A customer-provided value or an object that was sent with - identification request. - type: object - additionalProperties: true - linkedId: - description: A customer-provided id that was sent with identification request. - type: string - example: someID - confidence: - $ref: '#/components/schemas/Confidence' - visitorFound: - description: Attribute represents if a visitor had been identified before. - type: boolean - firstSeenAt: - $ref: '#/components/schemas/SeenAt' - lastSeenAt: - $ref: '#/components/schemas/SeenAt' - additionalProperties: false - required: - - visitorId - - browserDetails - - firstSeenAt - - incognito - - ip - - lastSeenAt - - requestId - - time - - timestamp - - url - - visitorFound + $ref: '#/components/schemas/WebhookDeveloperTools' 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. - type: string - example: Ibk1527CUFmcnjLwIs4A - required: - - visitorId RelatedVisitorsResponse: type: object additionalProperties: false + required: + - relatedVisitors properties: relatedVisitors: type: array items: $ref: '#/components/schemas/RelatedVisitor' - required: - - relatedVisitors diff --git a/schemas/fingerprint-server-api-readme-explorer.yaml b/schemas/fingerprint-server-api-readme-explorer.yaml index 37a51adb..73a091b4 100644 --- a/schemas/fingerprint-server-api-readme-explorer.yaml +++ b/schemas/fingerprint-server-api-readme-explorer.yaml @@ -63,22 +63,22 @@ paths: parameters: - name: request_id in: path - description: >- - The unique - [identifier](https://dev.fingerprint.com/docs/js-agent#requestid) of - each identification request. required: true schema: type: string + description: >- + The unique + [identifier](https://dev.fingerprint.com/reference/get-function#requestid) + of each identification request. responses: '200': - description: OK + description: OK. content: application/json: schema: - $ref: '#/components/schemas/EventResponse' + $ref: '#/components/schemas/EventsGetResponse' examples: - fullResponse: + 200-full: summary: Example response value: products: @@ -211,6 +211,7 @@ paths: vpn: data: result: false + confidence: high originTimezone: Europe/Berlin originCountry: unknown methods: @@ -218,7 +219,6 @@ paths: publicVPN: false auxiliaryMobile: false osMismatch: false - confidence: high proxy: data: result: false @@ -320,14 +320,14 @@ paths: developerTools: data: result: false - allErrorsResponse: + 200-all-errors: summary: All failed signals value: products: identification: error: code: Failed - message: failed + message: internal server error botd: error: code: Failed @@ -426,61 +426,29 @@ paths: error: code: Failed message: internal server error - withBotdError: - summary: BotD error + 200-identification-error: + summary: Identification error value: products: identification: - data: - visitorId: Ibk1527CUFmcnjLwIs4A9 - requestId: 0KSh65EnVoB85JBmloQK - incognito: true - linkedId: somelinkedId - time: '2019-05-21T16:40:13Z' - tag: {} - timestamp: 1582299576512 - url: https://www.example.com/login - ip: 61.127.217.15 - ipLocation: - accuracyRadius: 10 - latitude: 49.982 - longitude: 36.2566 - postalCode: '61202' - timezone: Europe/Dusseldorf - city: - name: Dusseldorf - continent: - code: EU - name: Europe - country: - code: DE - name: Germany - 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: true - firstSeenAt: - global: '2022-03-16T11:26:45.362Z' - subscription: '2022-03-16T11:31:01.101Z' - lastSeenAt: - global: '2022-03-16T11:28:34.023Z' - subscription: null - botd: error: code: Failed message: internal server error - withBotdTooManyRequestsError: - summary: BotD too many requests error + botd: + data: + bot: + result: bad + type: headlessChrome + url: https://example.com/login + ip: 94.60.143.223 + time: '2024-02-23T10:20:25.287Z' + userAgent: >- + Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) + AppleWebKit/537.36 (KHTML, like Gecko) + HeadlessChrome/121.0.6167.57 Safari/537.36 + requestId: 1708683625245.tuJ4nD + 200-botd-error: + summary: BotD error value: products: identification: @@ -489,8 +457,8 @@ paths: requestId: 0KSh65EnVoB85JBmloQK incognito: true linkedId: somelinkedId - tag: {} time: '2019-05-21T16:40:13Z' + tag: {} timestamp: 1582299576512 url: https://www.example.com/login ip: 61.127.217.15 @@ -529,32 +497,11 @@ paths: global: '2022-03-16T11:28:34.023Z' subscription: null botd: - error: - code: TooManyRequests - message: too many requests - withIdentificationError: - summary: Identification error - value: - products: - identification: error: code: Failed - message: failed - botd: - data: - bot: - result: bad - type: headlessChrome - url: https://example.com/login - ip: 94.60.143.223 - time: '2024-02-23T10:20:25.287Z' - userAgent: >- - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) - AppleWebKit/537.36 (KHTML, like Gecko) - HeadlessChrome/121.0.6167.57 Safari/537.36 - requestId: 1708683625245.tuJ4nD - withIdentificationTooManyRequestsError: - summary: Identification too many requests error + message: internal server error + 200-too-many-requests-error: + summary: Too many requests error value: products: identification: @@ -562,40 +509,49 @@ paths: code: 429 Too Many Requests message: too many requests botd: - data: - bot: - result: bad - type: headlessChrome - url: https://example.com/login - ip: 94.60.143.223 - time: '2024-02-23T10:20:25.287Z' - userAgent: >- - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) - AppleWebKit/537.36 (KHTML, like Gecko) - HeadlessChrome/121.0.6167.57 Safari/537.36 - requestId: 1708683625245.tuJ4nD + error: + code: TooManyRequests + message: too many requests '403': - description: Forbidden + description: Forbidden. Access to this API is denied. content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon403Response' + $ref: '#/components/schemas/ErrorResponse' examples: - example: - summary: Forbidden + 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 is different from the + region, the calling application is configured with. + value: + error: + code: WrongRegion + message: wrong region '404': - description: Not found + description: >- + Not found. The request ID cannot be found in this application's + data. content: application/json: schema: - $ref: '#/components/schemas/ErrorEvent404Response' + $ref: '#/components/schemas/ErrorResponse' examples: - example: - summary: Not found + 404-request-not-found: + summary: Error response when the provided request ID does not exist. value: error: code: RequestNotFound @@ -782,69 +738,89 @@ paths: parameters: - name: request_id in: path - description: >- - The unique event - [identifier](https://dev.fingerprint.com/docs/js-agent#requestid). required: true schema: type: string + description: >- + The unique event + [identifier](https://dev.fingerprint.com/reference/get-function#requestid). requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/EventUpdateRequest' + $ref: '#/components/schemas/EventsUpdateRequest' responses: '200': - description: OK + description: OK. '400': - description: Bad request + description: Bad request. The request payload is not valid. content: application/json: schema: - $ref: '#/components/schemas/ErrorUpdateEvent400Response' + $ref: '#/components/schemas/ErrorResponse' examples: example: - summary: Example response + summary: >- + Error response when the specified request payload is not + valid and cannot be parsed. value: error: code: RequestCannotBeParsed message: request body is not valid '403': - description: Forbidden + description: Forbidden. Access to this API is denied. content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon403Response' + $ref: '#/components/schemas/ErrorResponse' examples: - example: - summary: Example response + 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 is different from the + region, the calling application is configured with. + value: + error: + code: WrongRegion + message: wrong region '404': - description: Not found + description: >- + Not found. The request ID cannot be found in this application's + data. content: application/json: schema: - $ref: '#/components/schemas/ErrorEvent404Response' + $ref: '#/components/schemas/ErrorResponse' examples: - example: - summary: Example response + 404-request-not-found: + summary: Error response when the provided request ID does not exist. value: error: code: RequestNotFound message: request id is not found '409': - description: Conflict + description: Conflict. The event is not mutable yet. content: application/json: schema: - $ref: '#/components/schemas/ErrorUpdateEvent409Response' + $ref: '#/components/schemas/ErrorResponse' examples: example: - summary: Example response + summary: Error response when the event is not mutable yet. value: error: code: StateNotReady @@ -871,16 +847,18 @@ paths: response is received. parameters: - name: visitor_id - description: >- - Unique [visitor - identifier](https://dev.fingerprint.com/docs/js-agent#visitorid) - issued by Fingerprint Pro. in: path required: true schema: type: string - example: uYIm7Ksp5rf00SllPhFp + description: >- + Unique [visitor + identifier](https://dev.fingerprint.com/reference/get-function#visitorid) + issued by Fingerprint Pro. - name: request_id + in: query + schema: + type: string description: > Filter visits by `requestId`. @@ -888,27 +866,29 @@ paths: Every identification request has a unique identifier associated with it called `requestId`. This identifier is returned to the client in the identification - [result](https://dev.fingerprint.com/docs/js-agent#requestid). When - you filter visits by `requestId`, only one visit will be returned. + [result](https://dev.fingerprint.com/reference/get-function#requestid). + When you filter visits by `requestId`, only one visit will be + returned. + - name: linked_id in: query schema: type: string - - name: linked_id description: > Filter visits by your custom identifier. You can use - [`linkedId`](https://dev.fingerprint.com/docs/js-agent#linkedid) to - associate identification requests with your own identifier, for + [`linkedId`](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: limit in: query schema: - type: string - required: false - - name: limit + type: integer + format: int32 + minimum: 0 description: > Limit scanned results. @@ -921,12 +901,10 @@ paths: By default, the most recent 100 visits are scanned, the maximum is 500. + - name: paginationKey in: query schema: - type: integer - format: int32 - minimum: 0 - - name: paginationKey + type: string description: > Use `paginationKey` to get the next page of results. @@ -951,28 +929,25 @@ paths: get less visits than the `limit` you specified with more available on the next page. When there are no more results available for scanning, the `paginationKey` attribute is not returned. - in: query - schema: - type: string - required: false - name: before - description: > - ⚠️ Deprecated pagination method, please use `paginationKey` instead. - Timestamp (in milliseconds since epoch) used to paginate results. 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. responses: '200': - description: OK + description: OK. content: application/json: schema: - $ref: '#/components/schemas/Response' + $ref: '#/components/schemas/VisitorsGetResponse' examples: - limit1: + 200-limit-1: summary: Example response with limit=1 value: visitorId: AcxioeQKffpXF8iGQK3P @@ -989,7 +964,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 82.118.30.68 ipLocation: @@ -1024,7 +998,7 @@ paths: subscription: '2022-06-16T10:03:00.912Z' lastTimestamp: 1655373953086 paginationKey: 1655373953086.DDlfmP - limit500: + 200-limit-500: summary: Example response with limit=500 value: visitorId: AcxioeQKffpXF8iGQK3P @@ -1041,7 +1015,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 188.242.36.107 ipLocation: @@ -1086,7 +1059,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 82.118.30.62 ipLocation: @@ -1131,7 +1103,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 82.118.30.68 ipLocation: @@ -1176,7 +1147,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 82.118.30.91 ipLocation: @@ -1221,7 +1191,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 188.242.36.107 ipLocation: @@ -1266,7 +1235,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.137 timestamp: 1655106799878 @@ -1294,7 +1262,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.157 ipLocation: @@ -1326,7 +1293,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 188.242.36.107 ipLocation: @@ -1356,7 +1322,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 188.242.36.107 ipLocation: @@ -1401,7 +1366,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 188.242.36.107 ipLocation: @@ -1446,7 +1410,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1490,7 +1453,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1534,7 +1496,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1578,7 +1539,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.64 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1622,7 +1582,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1666,7 +1625,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1710,7 +1668,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1754,7 +1711,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1798,7 +1754,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1842,7 +1797,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36 - botProbability: 0 incognito: false ip: 217.150.54.233 ipLocation: @@ -1887,7 +1841,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36 - botProbability: 0 incognito: true ip: 217.150.54.233 ipLocation: @@ -1932,7 +1885,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36 - botProbability: 0 incognito: false ip: 217.150.54.233 ipLocation: @@ -1977,7 +1929,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -2021,7 +1972,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -2065,7 +2015,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.157 ipLocation: @@ -2109,7 +2058,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -2153,7 +2101,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 188.242.36.107 ipLocation: @@ -2198,7 +2145,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 84.247.59.113 ipLocation: @@ -2243,7 +2189,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 84.247.59.113 ipLocation: @@ -2288,7 +2233,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 84.247.59.146 ipLocation: @@ -2333,7 +2277,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 84.247.59.146 ipLocation: @@ -2378,7 +2321,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.105 ipLocation: @@ -2417,7 +2359,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.99 ipLocation: @@ -2456,7 +2397,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.99 ipLocation: @@ -2495,7 +2435,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.96 ipLocation: @@ -2534,7 +2473,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.96 ipLocation: @@ -2573,7 +2511,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 188.242.36.107 ipLocation: @@ -2618,7 +2555,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.227 ipLocation: @@ -2657,7 +2593,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.89 ipLocation: @@ -2696,7 +2631,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.111 ipLocation: @@ -2735,7 +2669,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.111 ipLocation: @@ -2774,7 +2707,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.111 ipLocation: @@ -2813,7 +2745,6 @@ paths: Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.198 ipLocation: @@ -2852,7 +2783,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.198 ipLocation: @@ -2891,7 +2821,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.206 ipLocation: @@ -2930,7 +2859,6 @@ paths: Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.204 ipLocation: @@ -2969,7 +2897,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.204 ipLocation: @@ -3008,7 +2935,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.204 ipLocation: @@ -3047,7 +2973,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.204 ipLocation: @@ -3086,7 +3011,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.172 ipLocation: @@ -3125,7 +3049,6 @@ paths: Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.210 ipLocation: @@ -3164,7 +3087,6 @@ paths: Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.210 ipLocation: @@ -3203,7 +3125,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.180 ipLocation: @@ -3242,7 +3163,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.180 ipLocation: @@ -3281,7 +3201,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.75 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.195 ipLocation: @@ -3320,7 +3239,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.75 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.179 ipLocation: @@ -3359,7 +3277,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.60 Safari/537.36 - botProbability: 0 incognito: false ip: 109.245.35.200 ipLocation: @@ -3403,7 +3320,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.60 Safari/537.36 - botProbability: 0 incognito: false ip: 109.245.35.200 ipLocation: @@ -3447,7 +3363,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36 - botProbability: 0 incognito: false ip: 178.223.21.183 ipLocation: @@ -3491,7 +3406,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36 - botProbability: 0 incognito: false ip: 87.116.165.97 ipLocation: @@ -3535,7 +3449,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36 - botProbability: 0 incognito: false ip: 87.116.165.97 ipLocation: @@ -3579,7 +3492,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36 - botProbability: 0 incognito: false ip: 87.116.165.97 ipLocation: @@ -3611,19 +3523,36 @@ paths: lastSeenAt: global: '2022-03-08T12:33:05.677Z' subscription: '2022-03-08T12:33:05.677Z' + '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' + examples: + 400-bad-request: + summary: >- + Error response when the visitor ID or query parameters are + missing or in the wrong format. + value: + error: bad request '403': - description: Forbidden. The API Key is probably missing or incorrect. + description: Forbidden. Access to this API is denied. content: application/json: schema: - $ref: '#/components/schemas/ErrorVisits403' + $ref: '#/components/schemas/ErrorPlainResponse' examples: - example: - summary: Forbidden + 403-forbidden: + summary: >- + Error response when the secret API Key is missing or + incorrect. value: error: Forbidden (HTTP 403) '429': - description: Too Many Requests + description: Too Many Requests. The request is throttled. headers: Retry-After: description: >- @@ -3636,10 +3565,12 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/TooManyRequestsResponse' + $ref: '#/components/schemas/ErrorPlainResponse' examples: - example: - summary: Too Many Requests + 429-too-many-requests: + summary: >- + Error response when the limit on the provided secret API key + requests per second has been exceeded. value: error: too many requests x-readme: @@ -3871,13 +3802,13 @@ paths: parameters: - name: visitor_id in: path - description: >- - The [visitor - ID](https://dev.fingerprint.com/docs/js-agent#visitorid) you want to - delete. required: true schema: type: string + description: >- + The [visitor + ID](https://dev.fingerprint.com/reference/get-function#visitorid) + you want to delete. responses: '200': description: OK. The visitor ID is scheduled for deletion. @@ -3888,18 +3819,18 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorVisitor400Response' + $ref: '#/components/schemas/ErrorResponse' examples: - 400-empty-visitor-id: + 400-visitor-id-required: summary: >- Error response when the request does not include a visitor - ID + ID. value: error: code: RequestCannotBeParsed message: visitor id is required - 400-invalid-visitor-id: - summary: Error response when the visitor ID is incorrectly formatted + 400-visitor-id-invalid: + summary: Error response when the visitor ID is incorrectly formatted. value: error: code: RequestCannotBeParsed @@ -3909,16 +3840,14 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon403Response' + $ref: '#/components/schemas/ErrorResponse' examples: - 403-feature-not-enabled: - summary: >- - Error response when this feature is not enabled for a - subscription. + 403-token-required: + summary: Error response when the secret API key was not provided. value: error: - code: FeatureNotEnabled - message: feature not enabled + code: TokenRequired + message: secret key is required 403-token-not-found: summary: >- Error response when the provided secret API key does not @@ -3927,12 +3856,6 @@ paths: error: code: TokenNotFound message: secret key is not found - 403-token-required: - summary: Error response when the secret API key was not provided. - value: - error: - code: TokenRequired - message: secret key is required 403-wrong-region: summary: >- Error response when the API region is different from the @@ -3941,6 +3864,20 @@ paths: error: code: WrongRegion message: wrong region + 403-subscription-not-active: + summary: Error response when the subscription is not active. + value: + error: + code: FeatureNotEnabled + message: feature not enabled + 403-feature-not-enabled: + summary: >- + Error response when this feature is not enabled for a + subscription. + value: + error: + code: SubscriptionNotActive + message: forbidden '404': description: >- Not found. The visitor ID cannot be found in this application's @@ -3948,10 +3885,12 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorVisitor404Response' + $ref: '#/components/schemas/ErrorResponse' examples: - example: - summary: Not found + 404-visitor-not-found: + summary: >- + Error response when the visitor ID cannot be found in this + application's data. value: error: code: VisitorNotFound @@ -3961,10 +3900,12 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon429Response' + $ref: '#/components/schemas/ErrorResponse' examples: - example: - summary: Too Many Requests + 429-too-many-requests: + summary: >- + Error response when the limit on the provided secret API key + requests per second has been exceeded. value: error: code: TooManyRequests @@ -3983,117 +3924,218 @@ components: BrowserDetails: type: object additionalProperties: false + required: + - browserName + - browserFullVersion + - browserMajorVersion + - os + - osVersion + - device + - userAgent properties: browserName: type: string - example: Chrome browserMajorVersion: type: string - example: '101' browserFullVersion: type: string - example: 101.0.4951 os: type: string - example: Windows osVersion: type: string - example: '10' device: type: string - example: Other userAgent: type: string - example: >- - Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, - like Gecko) Chrome/101.0.4951.41 Safari/537.36 - botProbability: - type: integer + GeolocationCity: + type: object + additionalProperties: false required: - - browserFullVersion - - browserMajorVersion - - browserName - - device - - os - - osVersion - - userAgent - title: BrowserDetails - Location: + - name + properties: + name: + type: string + GeolocationCountry: type: object additionalProperties: false + required: + - code + - name properties: code: type: string minLength: 2 maxLength: 2 - example: US name: type: string - example: United States + GeolocationContinent: + type: object + additionalProperties: false required: - code - name - title: Location - Subdivision: + properties: + code: + type: string + minLength: 2 + maxLength: 2 + name: + type: string + GeolocationSubdivision: type: object additionalProperties: false + required: + - isoCode + - name properties: isoCode: type: string - example: '10' name: type: string - example: Hlavni mesto Praha - Confidence: + 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://dev.fingerprint.com/docs/smart-signals-overview#ip-geolocation) + for geolocation information. additionalProperties: false properties: - score: + accuracyRadius: + type: integer + minimum: 0 description: >- - The confidence score is a floating-point number between 0 and 1 that - represents the probability of accurate identification. + 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: float + 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 - required: - - score - title: Confidence - SeenAt: + IdentificationSeenAt: type: object additionalProperties: false + required: + - global + - subscription properties: global: type: string nullable: true format: date-time - example: '2022-05-05T18:28:54.535Z' subscription: type: string nullable: true format: date-time - example: '2022-06-09T22:58:05.576Z' - required: - - global - - subscription - title: SeenAt - example: - global: '2022-05-05T18:28:54.535Z' - subscription: null - Visit: + 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' + Identification: + type: object + additionalProperties: false + required: + - visitorId + - requestId + - browserDetails + - incognito + - ip + - timestamp + - time + - url + - tag + - visitorFound + - firstSeenAt + - lastSeenAt + properties: + visitorId: + type: string + description: >- + String of 20 characters that uniquely identifies the visitor's + browser. requestId: - description: Unique identifier of the user's identification request. type: string - example: 1654815516083.OX6kx8 + description: Unique identifier of the user's request. browserDetails: $ref: '#/components/schemas/BrowserDetails' incognito: @@ -4102,283 +4144,293 @@ components: ip: type: string format: ipv4 - example: 8.8.8.8 + description: IP address of the requesting browser or bot. ipLocation: - type: object - additionalProperties: false - deprecated: true - 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. - properties: - accuracyRadius: - description: >- - The IP address is likely to be within this radius (in km) of the - specified location. - type: integer - minimum: 0 - 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: - type: object - additionalProperties: false - title: DeprecatedIPLocationCity - properties: - name: - type: string - country: - $ref: '#/components/schemas/Location' - continent: - $ref: '#/components/schemas/Location' - subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: DeprecatedIPLocation + $ref: '#/components/schemas/DeprecatedGeolocation' + linkedId: + type: string + description: A customer-provided id that was sent with the request. timestamp: description: Timestamp of the event with millisecond precision in Unix time. type: integer format: int64 - example: 1654815516086 time: - title: Time - description: Time expressed according to ISO 8601 in UTC format. type: string format: date-time - example: '2022-06-09T22:58:36Z' + 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: - description: Page URL from which the identification request was sent. type: string - example: https://some.website/path?query=params + description: Page URL from which the request was sent. tag: - description: >- - A customer-provided value or an object that was sent with - identification request. - type: object - additionalProperties: true - linkedId: - description: A customer-provided id that was sent with identification request. - type: string - example: someID + $ref: '#/components/schemas/Tag' confidence: - $ref: '#/components/schemas/Confidence' + $ref: '#/components/schemas/IdentificationConfidence' visitorFound: - description: Attribute represents if a visitor had been identified before. type: boolean + description: Attribute represents if a visitor had been identified before. firstSeenAt: - $ref: '#/components/schemas/SeenAt' + $ref: '#/components/schemas/IdentificationSeenAt' lastSeenAt: - $ref: '#/components/schemas/SeenAt' - required: - - browserDetails - - firstSeenAt - - incognito - - ip - - lastSeenAt - - requestId - - time - - timestamp - - url - - visitorFound - title: Visit - IdentificationError: + $ref: '#/components/schemas/IdentificationSeenAt' + components: + $ref: '#/components/schemas/RawDeviceAttributes' + ErrorCode: + type: string + enum: + - RequestCannotBeParsed + - TokenRequired + - TokenNotFound + - SubscriptionNotActive + - WrongRegion + - FeatureNotEnabled + - 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. + * `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: - type: string - description: | - Error code: - * `429 Too Many Requests` - the limit on secret API key requests per second has been exceeded - * `Failed` - internal server error - enum: - - 429 Too Many Requests - - Failed - example: 429 Too Many Requests + $ref: '#/components/schemas/ErrorCode' message: type: string - example: too many requests - required: - - code - - message - BotdDetectionResult: + 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: - type: string - 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 - enum: - - notDetected - - good - - bad - example: bad + $ref: '#/components/schemas/BotdBotResult' type: type: string - example: selenium - required: - - result - BotdResult: + Botd: type: object - additionalProperties: false 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 format: ipv4 - example: 8.8.8.8 description: IP address of the requesting browser or bot. time: - title: Time + type: string + format: date-time 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 - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - url: - description: Page URL from which identification request was sent. - type: string - example: https://example.com/login + malicious. Otherwise, request replay attacks are possible. userAgent: type: string - example: >- - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 - (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 requestId: type: string - example: 1681392853693.lRiBBD - linkedId: - type: string - example: Automatic tests bot - bot: - $ref: '#/components/schemas/BotdDetectionResult' + 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: - - bot - - url - - ip - - time - - userAgent - - requestId - ProductError: + - 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: - code: - type: string - description: | - Error code: - * `TooManyRequests` - the limit on secret API key requests per second has been exceeded - * `Failed` - internal server error - enum: - - TooManyRequests - - Failed - example: TooManyRequests - message: - type: string - example: too many requests + data: + $ref: '#/components/schemas/RootApps' + error: + $ref: '#/components/schemas/Error' + Emulator: + type: object + additionalProperties: false required: - - code - - message - IPLocation: + - 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. - type: integer - minimum: 0 - example: 1000 latitude: type: number format: double minimum: -90 maximum: 90 - example: 37.75 longitude: type: number format: double minimum: -180 maximum: 180 - example: -97.82 postalCode: type: string - example: 130 00 timezone: type: string format: timezone - example: America/Chicago city: - type: object - additionalProperties: false - title: IPLocationCity - properties: - name: - type: string - example: Prague + $ref: '#/components/schemas/GeolocationCity' country: - $ref: '#/components/schemas/Location' + $ref: '#/components/schemas/GeolocationCountry' continent: - $ref: '#/components/schemas/Location' + $ref: '#/components/schemas/GeolocationContinent' subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: IPLocation - ASN: + $ref: '#/components/schemas/GeolocationSubdivisions' + IPInfoASN: type: object additionalProperties: false + required: + - asn + - name + - network properties: asn: type: string - example: '7922' - network: - type: string - example: 73.136.0.0/13 name: type: string - example: COMCAST-7922 - required: - - asn - - network - title: ASN - DataCenter: + network: + type: string + IPInfoDataCenter: type: object additionalProperties: false + required: + - result + - name properties: result: type: boolean name: type: string - example: DediPath + IPInfoV4: + type: object + additionalProperties: false required: - - result - title: DataCenter - IpInfoResult: + - 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 @@ -4386,362 +4438,414 @@ components: additionalProperties: false properties: v4: - type: object - additionalProperties: false - properties: - address: - type: string - format: ipv4 - example: 94.142.239.124 - geolocation: - $ref: '#/components/schemas/IPLocation' - asn: - $ref: '#/components/schemas/ASN' - datacenter: - $ref: '#/components/schemas/DataCenter' - required: - - address - - geolocation + $ref: '#/components/schemas/IPInfoV4' v6: - type: object - additionalProperties: false - properties: - address: - type: string - format: ipv6 - example: 2001:0db8:85a3:0000:0000:8a2e:0370:7334 - geolocation: - $ref: '#/components/schemas/IPLocation' - asn: - $ref: '#/components/schemas/ASN' - datacenter: - $ref: '#/components/schemas/DataCenter' - required: - - address - - geolocation - IncognitoResult: + $ref: '#/components/schemas/IPInfoV6' + ProductIPInfo: type: object additionalProperties: false properties: - result: + data: + $ref: '#/components/schemas/IPInfo' + error: + $ref: '#/components/schemas/Error' + IPBlocklistDetails: + type: object + additionalProperties: false + required: + - emailSpam + - attackSource + properties: + emailSpam: type: boolean - description: > - `true` if we detected incognito mode used in the browser, `false` - otherwise. - example: false + 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 - RootAppsResult: + - 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: > - 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. - example: false + `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 + 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. + VPN: + type: object + additionalProperties: false required: - result - EmulatorResult: + - 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' + ProductVPN: type: object additionalProperties: false + properties: + data: + $ref: '#/components/schemas/VPN' + error: + $ref: '#/components/schemas/Error' + Proxy: + 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. - example: false + `true` if the request IP address is used by a public proxy provider, + `false` otherwise. + ProductProxy: + type: object + additionalProperties: false + properties: + data: + $ref: '#/components/schemas/Proxy' + error: + $ref: '#/components/schemas/Error' + Incognito: + type: object + additionalProperties: false required: - result - ClonedAppResult: + 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 + - anomalyScore + - antiDetectBrowser 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. - example: false + Flag indicating browser tampering was detected. This happens when + either of these conditions is true: + * There are inconsistencies in the browser configuration that cross our internal tampering thresholds (indicated by `anomalyScore`). + * The browser signature resembles one of "anti-detect" browsers specifically designed to evade identification and fingerprinting, for example, Incognition (indicated by `antiDetectBrowser`). + anomalyScore: + type: number + format: double + minimum: 0 + maximum: 1 + description: | + Confidence score (`0.0 - 1.0`) for tampering detection: + * Values above `0.5` indicate that there was a tampering attempt. + * Values below `0.5` indicate genuine browsers. + antiDetectBrowser: + type: boolean + description: >- + Is `true` if the identified browser resembles one of "anti-detect" + browsers, for example, Incognition. Anti-detect browsers try to + evade identification by masking or manipulating their fingerprint to + imitate legitimate browser configurations. + ProductTampering: + type: object + additionalProperties: false + properties: + data: + $ref: '#/components/schemas/Tampering' + error: + $ref: '#/components/schemas/Error' + ClonedApp: + type: object + additionalProperties: false required: - result - FactoryResetResult: + 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 + 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. - type: string - format: date-time - example: '2022-06-09T22:58:36Z' 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. - type: integer - format: int64 - example: 1654815517198 - required: - - time - - timestamp - JailbrokenResult: + ProductFactoryReset: 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. - example: false - required: - - result - FridaResult: + data: + $ref: '#/components/schemas/FactoryReset' + error: + $ref: '#/components/schemas/Error' + Jailbroken: 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. - example: false required: - result - IpBlockListResult: - 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. - example: false - details: - type: object - additionalProperties: false - properties: - emailSpam: - type: boolean - description: IP address was part of a known email spam attack (SMTP). - example: false - attackSource: - type: boolean - description: IP address was part of a known network attack (SSH/HTTPS). - example: false - required: - - emailSpam - - attackSource - required: - - result - - details - TorResult: + 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: - result: - type: boolean - description: > - `true` if the request IP address is a known tor exit node, `false` - otherwise. - example: false - required: - - result - PrivacySettingsResult: + data: + $ref: '#/components/schemas/Jailbroken' + error: + $ref: '#/components/schemas/Error' + Frida: 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`. - example: false - required: - - result - VirtualMachineResult: + [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: - result: - type: boolean - description: > - `true` if the request came from a browser running inside a virtual - machine (e.g. VMWare), `false` otherwise. - example: false - required: - - result - VpnResult: + data: + $ref: '#/components/schemas/Frida' + error: + $ref: '#/components/schemas/Error' + PrivacySettings: type: object additionalProperties: false + required: + - result properties: result: type: boolean - description: >- - VPN or other anonymizing service has been used when sending the - request. - example: false - originTimezone: - type: string - description: Local timezone which is used in timezoneMismatch method. - example: Europe/Berlin - originCountry: - type: string - description: >- - Country of the request (only for Android SDK version >= 2.4.0, ISO - 3166 format or unknown). - example: unknown - methods: - type: object - additionalProperties: false - properties: - timezoneMismatch: - type: boolean - description: >- - The browser timezone doesn't match the timezone inferred from - the request IP address. - example: false - publicVPN: - type: boolean - description: >- - Request IP address is owned and used by a public VPN service - provider. - example: false - 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. - example: false - osMismatch: - type: boolean - description: >- - The browser runs on a different operating system than the - operating system inferred from the request network signature. - example: false - required: - - timezoneMismatch - - publicVPN - - auxiliaryMobile - - osMismatch - confidence: - 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. - example: low - required: - - result - - originTimezone - - methods - - confidence - ProxyResult: + 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 IP address is used by a public proxy provider, - `false` otherwise. - example: false - required: - - result - TamperingResult: + `true` if the request came from a browser running inside a virtual + machine (e.g. VMWare), `false` otherwise. + ProductVirtualMachine: type: object additionalProperties: false properties: - result: - type: boolean - description: >- - Flag indicating browser tampering was detected. This happens when - either of these conditions is true: - * There are inconsistencies in the browser configuration that cross our internal tampering thresholds (indicated by `anomalyScore`). - * The browser signature resembles one of "anti-detect" browsers specifically designed to evade identification and fingerprinting, for example, Incognition (indicated by `antiDetectBrowser`). - example: false - anomalyScore: - type: number - description: >- - Confidence score (`0.0 - 1.0`) for tampering detection. Values above - `0.5` indicate that there was a tampering attempt. Values below - `0.5` indicate genuine browsers. - example: 0 - minimum: 0 - maximum: 1 - antiDetectBrowser: - type: boolean - description: >- - Is `true` if the identified browser resembles one of "anti-detect" - browsers, for example, Incognition. Anti-detect browsers try to - evade identification by masking or manipulating their fingerprint to - imitate legitimate browser configurations. - example: false - required: - - result - - anomalyScore - - antiDetectBrowser - HighActivityResult: + 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 whether the request came from a high activity - visitor. - example: false + description: Flag indicating if the request came from a high-activity visitor. dailyRequests: - type: number - description: Number of requests from the same visitor in the previous day. - example: 10 + type: integer + format: int64 minimum: 1 - required: - - result - LocationSpoofingResult: + 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' + 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. - example: false - required: - - result - SuspectScoreResult: + 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 @@ -4752,66 +4856,47 @@ components: 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 - example: 0 - required: - - result - RawDeviceAttributesResult: + ProductSuspectScore: 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: - type: object - properties: - error: - properties: - name: - title: error.name - type: string - message: - title: error.message - type: string - required: - - name - - message - title: error - type: object - value: - title: value - RemoteControlResult: + additionalProperties: false + properties: + data: + $ref: '#/components/schemas/SuspectScore' + error: + $ref: '#/components/schemas/Error' + RemoteControl: type: object 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. - example: false - required: - - result - VelocityIntervalResult: + ProductRemoteControl: + type: object + 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 - example: 1 1h: type: integer - example: 1 24h: type: integer description: > @@ -4820,17 +4905,13 @@ components: `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. - example: 1 - required: - - 5m - - 1h - VelocityIntervals: + VelocityData: type: object additionalProperties: false properties: intervals: - $ref: '#/components/schemas/VelocityIntervalResult' - VelocityResult: + $ref: '#/components/schemas/VelocityIntervals' + Velocity: type: object description: > Sums key data points for a specific `visitorId`, `ipAddress` and @@ -4839,15 +4920,16 @@ components: intervals: 5 minutes, 1 hour, and 24 hours as follows: - - Number of identification events associated with the visitor ID. + - Number of distinct IP addresses associated to the visitor ID. - Number of distinct linked IDs associated with the visitor ID. - - Number of distinct IP addresses associated to the visitor ID. - - Number of distinct countries associated with the visitor ID. - - Number of events associated for the detected IP address. + - 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. @@ -4865,42 +4947,57 @@ components: hours (`events.intervals.['24h']`) is higher than 20.000. additionalProperties: false - properties: - events: - $ref: '#/components/schemas/VelocityIntervals' - distinctLinkedId: - $ref: '#/components/schemas/VelocityIntervals' - distinctIp: - $ref: '#/components/schemas/VelocityIntervals' - distinctCountry: - $ref: '#/components/schemas/VelocityIntervals' - ipEvents: - $ref: '#/components/schemas/VelocityIntervals' - distinctIpByLinkedId: - $ref: '#/components/schemas/VelocityIntervals' - distinctVisitorIdByLinkedId: - $ref: '#/components/schemas/VelocityIntervals' required: - - events - - distinctLinkedId - distinctIp + - distinctLinkedId - distinctCountry + - events - ipEvents - distinctIpByLinkedId - distinctVisitorIdByLinkedId - DeveloperToolsResult: + 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 is Chrome with DevTools open or Firefox with Developer Tools open, `false` otherwise. - example: false - required: - - result - ProductsResponse: + ProductDeveloperTools: + type: object + additionalProperties: false + properties: + data: + $ref: '#/components/schemas/DeveloperTools' + error: + $ref: '#/components/schemas/Error' + Products: type: object description: >- Contains all information about the request identified by `requestId`, @@ -4908,709 +5005,179 @@ components: additionalProperties: false properties: identification: - type: object - additionalProperties: false - title: ProductsResponseIdentification - properties: - data: - title: ProductsResponseIdentificationData - type: object - properties: - requestId: - description: Unique identifier of the user's identification request. - type: string - example: 1654815516083.OX6kx8 - browserDetails: - $ref: '#/components/schemas/BrowserDetails' - incognito: - description: Flag if user used incognito session. - type: boolean - ip: - type: string - format: ipv4 - example: 8.8.8.8 - ipLocation: - type: object - additionalProperties: false - deprecated: true - 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. - properties: - accuracyRadius: - description: >- - The IP address is likely to be within this radius (in - km) of the specified location. - type: integer - minimum: 0 - 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: - type: object - additionalProperties: false - title: DeprecatedIPLocationCity - properties: - name: - type: string - country: - $ref: '#/components/schemas/Location' - continent: - $ref: '#/components/schemas/Location' - subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: DeprecatedIPLocation - timestamp: - description: >- - Timestamp of the event with millisecond precision in Unix - time. - type: integer - format: int64 - example: 1654815516086 - time: - title: Time - description: Time expressed according to ISO 8601 in UTC format. - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - url: - description: Page URL from which the identification request was sent. - type: string - example: https://some.website/path?query=params - tag: - description: >- - A customer-provided value or an object that was sent with - identification request. - type: object - additionalProperties: true - linkedId: - description: >- - A customer-provided id that was sent with identification - request. - type: string - example: someID - confidence: - $ref: '#/components/schemas/Confidence' - visitorFound: - description: >- - Attribute represents if a visitor had been identified - before. - type: boolean - firstSeenAt: - $ref: '#/components/schemas/SeenAt' - lastSeenAt: - $ref: '#/components/schemas/SeenAt' - visitorId: - type: string - description: > - String of 20 characters that uniquely identifies the - visitor's browser. - example: - - Ibk1527CUFmcnjLwIs4A - additionalProperties: false - required: - - browserDetails - - firstSeenAt - - incognito - - ip - - lastSeenAt - - requestId - - time - - timestamp - - url - - visitorFound - - visitorId - - tag - error: - $ref: '#/components/schemas/IdentificationError' + $ref: '#/components/schemas/ProductIdentification' botd: - title: ProductsResponseBotd - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/BotdResult' - error: - $ref: '#/components/schemas/ProductError' - ipInfo: - title: SignalResponseIpInfo - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/IpInfoResult' - error: - $ref: '#/components/schemas/ProductError' - incognito: - title: SignalResponseIncognito - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/IncognitoResult' - error: - $ref: '#/components/schemas/IdentificationError' + $ref: '#/components/schemas/ProductBotd' rootApps: - title: SignalResponseRootApps - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/RootAppsResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductRootApps' emulator: - title: SignalResponseEmulator - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/EmulatorResult' - error: - $ref: '#/components/schemas/ProductError' + $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: - title: SignalResponseClonedApp - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/ClonedAppResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductClonedApp' factoryReset: - title: SignalResponseFactoryReset - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/FactoryResetResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductFactoryReset' jailbroken: - title: SignalResponseJailbroken - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/JailbrokenResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductJailbroken' frida: - title: SignalResponseFrida - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/FridaResult' - error: - $ref: '#/components/schemas/ProductError' - ipBlocklist: - title: SignalResponseIpBlocklist - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/IpBlockListResult' - error: - $ref: '#/components/schemas/ProductError' - tor: - title: SignalResponseTor - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/TorResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductFrida' privacySettings: - title: SignalResponsePrivacySettings - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/PrivacySettingsResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductPrivacySettings' virtualMachine: - title: SignalResponseVirtualMachine - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/VirtualMachineResult' - error: - $ref: '#/components/schemas/ProductError' - vpn: - title: SignalResponseVpn - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/VpnResult' - error: - $ref: '#/components/schemas/ProductError' - proxy: - title: SignalResponseProxy - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/ProxyResult' - error: - $ref: '#/components/schemas/ProductError' - tampering: - title: SignalResponseTampering - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/TamperingResult' - error: - $ref: '#/components/schemas/IdentificationError' + $ref: '#/components/schemas/ProductVirtualMachine' + rawDeviceAttributes: + $ref: '#/components/schemas/ProductRawDeviceAttributes' highActivity: - title: SignalResponseHighActivity - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/HighActivityResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductHighActivity' locationSpoofing: - title: SignalResponseLocationSpoofing - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/LocationSpoofingResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductLocationSpoofing' suspectScore: - title: SignalResponseSuspectScore - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/SuspectScoreResult' - error: - $ref: '#/components/schemas/ProductError' - rawDeviceAttributes: - title: SignalResponseRawDeviceAttributes - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/RawDeviceAttributesResult' - error: - $ref: '#/components/schemas/IdentificationError' + $ref: '#/components/schemas/ProductSuspectScore' remoteControl: - title: SignalResponseRemoteControl - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/RemoteControlResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductRemoteControl' velocity: - title: SignalResponseVelocity - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/VelocityResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductVelocity' developerTools: - title: SignalResponseDeveloperTools - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/DeveloperToolsResult' - error: - $ref: '#/components/schemas/ProductError' - EventResponse: + $ref: '#/components/schemas/ProductDeveloperTools' + EventsGetResponse: + type: object description: >- Contains results from all activated products - Fingerprint Pro, Bot Detection, and others. - type: object additionalProperties: false - properties: - products: - $ref: '#/components/schemas/ProductsResponse' - error: - $ref: '#/components/schemas/ProductError' required: - products - ErrorCommon403Response: - type: object - additionalProperties: false properties: - error: - type: object - additionalProperties: false - title: Common403ErrorResponse - properties: - code: - type: string - description: | - Error code: - * `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 - enum: - - TokenRequired - - TokenNotFound - - SubscriptionNotActive - - WrongRegion - - FeatureNotEnabled - example: TokenRequired - message: - type: string - example: secret key is required - required: - - code - - message - ErrorEvent404Response: + products: + $ref: '#/components/schemas/Products' + ErrorResponse: type: object additionalProperties: false + required: + - error properties: error: - type: object - additionalProperties: false - title: ErrorEvent404ResponseError - properties: - code: - type: string - description: | - Error code: - * `RequestNotFound` - The specified request ID was not found. It never existed, expired, or it has been deleted. - enum: - - RequestNotFound - example: RequestNotFound - message: - type: string - example: request id is not found - required: - - code - - message - EventUpdateRequest: + $ref: '#/components/schemas/Error' + EventsUpdateRequest: type: object properties: linkedId: type: string description: LinkedID value to assign to the existing event tag: - type: object - description: >- - Full `tag` value to be set to the existing event. Replaces any - existing `tag` payload completely. + $ref: '#/components/schemas/Tag' suspect: type: boolean description: Suspect flag indicating observed suspicious or fraudulent event - ErrorUpdateEvent400Response: - type: object - additionalProperties: false - properties: - error: - type: object - additionalProperties: false - title: ErrorUpdateEvent400ResponseError - properties: - code: - type: string - description: > - Error code: * `RequestCannotBeParsed` - the JSON content of the - request contains some errors that prevented us from parsing it - (wrong type/surpassed limits) * `Failed` - the event is more - than 10 days old and cannot be updated - enum: - - RequestCannotBeParsed - - Failed - example: RequestCannotBeParsed - message: - type: string - description: Details about the underlying issue with the input payload - example: suspect flag must be a boolean - required: - - code - - message - ErrorUpdateEvent409Response: + Visit: type: object additionalProperties: false + required: + - requestId + - browserDetails + - incognito + - ip + - timestamp + - time + - url + - tag + - visitorFound + - firstSeenAt + - lastSeenAt properties: - error: - type: object - additionalProperties: false - title: ErrorUpdateEvent409ResponseError - properties: - code: - type: string - description: > - Error code: * `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. - enum: - - StateNotReady - example: StateNotReady - message: - type: string - example: resource is not mutable yet, try again - required: - - code - - message - Response: + 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 + format: ipv4 + 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 + 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: >- + Pagination-related fields `lastTimestamp` and `paginationKey` are + included if you use a pagination parameter like `limit` or `before` and + there is more data available on the next page. additionalProperties: false + required: + - visitorId + - visits properties: visitorId: type: string visits: type: array items: - title: ResponseVisits - type: object - properties: - requestId: - description: Unique identifier of the user's identification request. - type: string - example: 1654815516083.OX6kx8 - browserDetails: - $ref: '#/components/schemas/BrowserDetails' - incognito: - description: Flag if user used incognito session. - type: boolean - ip: - type: string - format: ipv4 - example: 8.8.8.8 - ipLocation: - type: object - additionalProperties: false - deprecated: true - 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. - properties: - accuracyRadius: - description: >- - The IP address is likely to be within this radius (in km) - of the specified location. - type: integer - minimum: 0 - 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: - type: object - additionalProperties: false - title: DeprecatedIPLocationCity - properties: - name: - type: string - country: - $ref: '#/components/schemas/Location' - continent: - $ref: '#/components/schemas/Location' - subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: DeprecatedIPLocation - timestamp: - description: >- - Timestamp of the event with millisecond precision in Unix - time. - type: integer - format: int64 - example: 1654815516086 - time: - title: Time - description: Time expressed according to ISO 8601 in UTC format. - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - url: - description: Page URL from which the identification request was sent. - type: string - example: https://some.website/path?query=params - tag: - description: >- - A customer-provided value or an object that was sent with - identification request. - type: object - additionalProperties: true - linkedId: - description: >- - A customer-provided id that was sent with identification - request. - type: string - example: someID - confidence: - $ref: '#/components/schemas/Confidence' - visitorFound: - description: Attribute represents if a visitor had been identified before. - type: boolean - firstSeenAt: - $ref: '#/components/schemas/SeenAt' - lastSeenAt: - $ref: '#/components/schemas/SeenAt' - additionalProperties: false - required: - - browserDetails - - firstSeenAt - - incognito - - ip - - lastSeenAt - - requestId - - time - - timestamp - - url - - visitorFound - - tag + $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. - type: integer - format: int64 - example: 1654815517198 paginationKey: + type: string description: >- Request ID of the last visit in the current page of results. Use this value in the following request as the `paginationKey` parameter to get the next page of results. - type: string - example: 1654815517198.azN4IZ - required: - - visitorId - - visits - title: PaginatedResponse - description: >- - Fields `lastTimestamp` and `paginationKey` added when `limit` or - `before` parameter provided and there is more data to show - ErrorVisits403: + ErrorPlainResponse: type: object additionalProperties: false - properties: - error: - type: string - description: Error text. - example: Forbidden (HTTP 403) required: - error - TooManyRequestsResponse: - type: object - additionalProperties: false properties: error: type: string - description: Error text. - example: request throttled - required: - - error - ErrorVisitor400Response: - type: object - additionalProperties: false - properties: - error: - type: object - additionalProperties: false - properties: - code: - type: string - description: > - Error code: * `RequestCannotBeParsed` - The visitor ID parameter - is missing or in the wrong format. - enum: - - RequestCannotBeParsed - example: RequestCannotBeParsed - message: - type: string - example: invalid visitor id - required: - - code - - message - ErrorVisitor404Response: - type: object - additionalProperties: false - properties: - error: - type: object - additionalProperties: false - title: ErrorVisitor404ResponseError - properties: - code: - type: string - description: > - Error code: * `VisitorNotFound` - The specified visitor ID was - not found. It never existed or it may have already been deleted. - enum: - - VisitorNotFound - example: VisitorNotFound - message: - type: string - example: visitor not found - required: - - code - - message - ErrorCommon429Response: - type: object - additionalProperties: false - properties: - error: - type: object - additionalProperties: false - properties: - code: - type: string - description: | - Error code: * `TooManyRequests` - The request is throttled. - enum: - - TooManyRequests - example: TooManyRequests - message: - type: string - example: request throttled - required: - - code - - message diff --git a/schemas/fingerprint-server-api-schema-for-sdks.yaml b/schemas/fingerprint-server-api-schema-for-sdks.yaml index 4f428cd5..c5d9f22e 100644 --- a/schemas/fingerprint-server-api-schema-for-sdks.yaml +++ b/schemas/fingerprint-server-api-schema-for-sdks.yaml @@ -53,32 +53,34 @@ paths: parameters: - name: request_id in: path - description: >- - The unique - [identifier](https://dev.fingerprint.com/docs/js-agent#requestid) of - each identification request. required: true schema: type: string + description: >- + The unique + [identifier](https://dev.fingerprint.com/reference/get-function#requestid) + of each identification request. responses: '200': - description: OK + description: OK. content: application/json: schema: - $ref: '#/components/schemas/EventResponse' + $ref: '#/components/schemas/EventsGetResponse' '403': - description: Forbidden + description: Forbidden. Access to this API is denied. content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon403Response' + $ref: '#/components/schemas/ErrorResponse' '404': - description: Not found + description: >- + Not found. The request ID cannot be found in this application's + data. content: application/json: schema: - $ref: '#/components/schemas/ErrorEvent404Response' + $ref: '#/components/schemas/ErrorResponse' put: tags: - Fingerprint @@ -99,45 +101,47 @@ paths: parameters: - name: request_id in: path - description: >- - The unique event - [identifier](https://dev.fingerprint.com/docs/js-agent#requestid). required: true schema: type: string + description: >- + The unique event + [identifier](https://dev.fingerprint.com/reference/get-function#requestid). requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/EventUpdateRequest' + $ref: '#/components/schemas/EventsUpdateRequest' responses: '200': - description: OK + description: OK. '400': - description: Bad request + description: Bad request. The request payload is not valid. content: application/json: schema: - $ref: '#/components/schemas/ErrorUpdateEvent400Response' + $ref: '#/components/schemas/ErrorResponse' '403': - description: Forbidden + description: Forbidden. Access to this API is denied. content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon403Response' + $ref: '#/components/schemas/ErrorResponse' '404': - description: Not found + description: >- + Not found. The request ID cannot be found in this application's + data. content: application/json: schema: - $ref: '#/components/schemas/ErrorEvent404Response' + $ref: '#/components/schemas/ErrorResponse' '409': - description: Conflict + description: Conflict. The event is not mutable yet. content: application/json: schema: - $ref: '#/components/schemas/ErrorUpdateEvent409Response' + $ref: '#/components/schemas/ErrorResponse' /visitors/{visitor_id}: get: tags: @@ -160,16 +164,18 @@ paths: response is received. parameters: - name: visitor_id - description: >- - Unique [visitor - identifier](https://dev.fingerprint.com/docs/js-agent#visitorid) - issued by Fingerprint Pro. in: path required: true schema: type: string - example: uYIm7Ksp5rf00SllPhFp + description: >- + Unique [visitor + identifier](https://dev.fingerprint.com/reference/get-function#visitorid) + issued by Fingerprint Pro. - name: request_id + in: query + schema: + type: string description: > Filter visits by `requestId`. @@ -177,27 +183,29 @@ paths: Every identification request has a unique identifier associated with it called `requestId`. This identifier is returned to the client in the identification - [result](https://dev.fingerprint.com/docs/js-agent#requestid). When - you filter visits by `requestId`, only one visit will be returned. + [result](https://dev.fingerprint.com/reference/get-function#requestid). + When you filter visits by `requestId`, only one visit will be + returned. + - name: linked_id in: query schema: type: string - - name: linked_id description: > Filter visits by your custom identifier. You can use - [`linkedId`](https://dev.fingerprint.com/docs/js-agent#linkedid) to - associate identification requests with your own identifier, for + [`linkedId`](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: limit in: query schema: - type: string - required: false - - name: limit + type: integer + format: int32 + minimum: 0 description: > Limit scanned results. @@ -210,12 +218,10 @@ paths: By default, the most recent 100 visits are scanned, the maximum is 500. + - name: paginationKey in: query schema: - type: integer - format: int32 - minimum: 0 - - name: paginationKey + type: string description: > Use `paginationKey` to get the next page of results. @@ -240,34 +246,39 @@ paths: get less visits than the `limit` you specified with more available on the next page. When there are no more results available for scanning, the `paginationKey` attribute is not returned. - in: query - schema: - type: string - required: false - name: before - description: > - ⚠️ Deprecated pagination method, please use `paginationKey` instead. - Timestamp (in milliseconds since epoch) used to paginate results. 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. responses: '200': - description: OK + 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/Response' + $ref: '#/components/schemas/ErrorPlainResponse' '403': - description: Forbidden. The API Key is probably missing or incorrect. + description: Forbidden. Access to this API is denied. content: application/json: schema: - $ref: '#/components/schemas/ErrorVisits403' + $ref: '#/components/schemas/ErrorPlainResponse' '429': - description: Too Many Requests + description: Too Many Requests. The request is throttled. headers: Retry-After: description: >- @@ -280,7 +291,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/TooManyRequestsResponse' + $ref: '#/components/schemas/ErrorPlainResponse' delete: tags: - Fingerprint @@ -345,13 +356,13 @@ paths: parameters: - name: visitor_id in: path - description: >- - The [visitor - ID](https://dev.fingerprint.com/docs/js-agent#visitorid) you want to - delete. required: true schema: type: string + description: >- + The [visitor + ID](https://dev.fingerprint.com/reference/get-function#visitorid) + you want to delete. responses: '200': description: OK. The visitor ID is scheduled for deletion. @@ -362,13 +373,13 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorVisitor400Response' + $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. Access to this API is denied. content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon403Response' + $ref: '#/components/schemas/ErrorResponse' '404': description: >- Not found. The visitor ID cannot be found in this application's @@ -376,13 +387,13 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorVisitor404Response' + $ref: '#/components/schemas/ErrorResponse' '429': description: Too Many Requests. The request is throttled. content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon429Response' + $ref: '#/components/schemas/ErrorResponse' /webhook: trace: tags: @@ -391,6 +402,11 @@ paths: Fake path to describe webhook format. More information about webhooks can be found in the [documentation](https://dev.fingerprint.com/docs/webhooks) + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Webhook' responses: default: description: Dummy for the schema @@ -406,22 +422,17 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/WebhookVisit' + $ref: '#/components/schemas/Webhook' example: value: requestId: Px6VxbRC6WBkA39yeNH3 + url: https://banking.example.com/signup + ip: 216.3.128.12 tag: requestType: signup yourCustomId: 45321 - linkedId: any-string - visitorId: 3HNey93AkBW6CRbxV6xP - visitorFound: true - timestamp: 1554910997788 time: '2019-10-12T07:20:50.52Z' - incognito: false - url: https://banking.example.com/signup - clientReferrer: https://google.com?search=banking+services - ip: 216.3.128.12 + timestamp: 1554910997788 ipLocation: accuracyRadius: 1 city: @@ -439,6 +450,17 @@ paths: - isoCode: IL name: Illinois timezone: America/Chicago + linkedId: any-string + visitorId: 3HNey93AkBW6CRbxV6xP + visitorFound: true + confidence: + score: 0.97 + firstSeenAt: + global: '2022-03-16T11:26:45.362Z' + subscription: '2022-03-16T11:31:01.101Z' + lastSeenAt: + global: '2022-03-16T11:28:34.023Z' + subscription: null browserDetails: browserName: Chrome browserFullVersion: 73.0.3683.86 @@ -449,20 +471,18 @@ paths: userAgent: >- (Macintosh; Intel Mac OS X 10_14_3) Chrome/73.0.3683.86 - confidence: - score: 0.97 - firstSeenAt: - global: '2022-03-16T11:26:45.362Z' - subscription: '2022-03-16T11:31:01.101Z' - lastSeenAt: - global: '2022-03-16T11:28:34.023Z' - subscription: null + incognito: false + clientReferrer: https://google.com?search=banking+services bot: result: bad type: selenium userAgent: >- (Macintosh; Intel Mac OS X 10_14_3) Chrome/73.0.3683.86 + rootApps: + result: false + emulator: + result: false ipInfo: v4: address: 94.142.239.124 @@ -490,10 +510,6 @@ paths: datacenter: result: true name: DediPath - rootApps: - result: false - emulator: - result: false ipBlocklist: result: false details: @@ -503,6 +519,7 @@ paths: result: false vpn: result: false + confidence: high originTimezone: Europe/Berlin originCountry: unknown methods: @@ -510,7 +527,6 @@ paths: publicVPN: false auxiliaryMobile: false osMismatch: false - confidence: high proxy: result: false tampering: @@ -619,15 +635,15 @@ paths: reference](https://dev.fingerprint.com/reference/related-visitors-api). parameters: - name: visitor_id - description: >- - The [visitor - ID](https://dev.fingerprint.com/docs/js-agent#visitorid) for which - you want to find the other visitor IDs that originated from the same - mobile device. in: query required: true schema: type: string + description: >- + The [visitor + ID](https://dev.fingerprint.com/reference/get-function#visitorid) + for which you want to find the other visitor IDs that originated + from the same mobile device. responses: '200': description: OK. @@ -642,13 +658,13 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorVisitor400Response' + $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. Access to this API is denied. content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon403Response' + $ref: '#/components/schemas/ErrorResponse' '404': description: >- Not found. The visitor ID cannot be found in this application's @@ -656,13 +672,13 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorVisitor404Response' + $ref: '#/components/schemas/ErrorResponse' '429': description: Too Many Requests. The request is throttled. content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon429Response' + $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: ApiKeyHeader: @@ -677,117 +693,218 @@ components: BrowserDetails: type: object additionalProperties: false + required: + - browserName + - browserFullVersion + - browserMajorVersion + - os + - osVersion + - device + - userAgent properties: browserName: type: string - example: Chrome browserMajorVersion: type: string - example: '101' browserFullVersion: type: string - example: 101.0.4951 os: type: string - example: Windows osVersion: type: string - example: '10' device: type: string - example: Other userAgent: type: string - example: >- - Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, - like Gecko) Chrome/101.0.4951.41 Safari/537.36 - botProbability: - type: integer + GeolocationCity: + type: object + additionalProperties: false required: - - browserFullVersion - - browserMajorVersion - - browserName - - device - - os - - osVersion - - userAgent - title: BrowserDetails - Location: + - name + properties: + name: + type: string + GeolocationCountry: type: object additionalProperties: false + required: + - code + - name properties: code: type: string minLength: 2 maxLength: 2 - example: US name: type: string - example: United States + GeolocationContinent: + type: object + additionalProperties: false required: - code - name - title: Location - Subdivision: + properties: + code: + type: string + minLength: 2 + maxLength: 2 + name: + type: string + GeolocationSubdivision: type: object additionalProperties: false + required: + - isoCode + - name properties: isoCode: type: string - example: '10' name: type: string - example: Hlavni mesto Praha - Confidence: + 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://dev.fingerprint.com/docs/smart-signals-overview#ip-geolocation) + for geolocation information. additionalProperties: false properties: - score: + accuracyRadius: + type: integer + minimum: 0 description: >- - The confidence score is a floating-point number between 0 and 1 that - represents the probability of accurate identification. + 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: float + 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 - required: - - score - title: Confidence - SeenAt: + IdentificationSeenAt: type: object additionalProperties: false + required: + - global + - subscription properties: global: type: string nullable: true format: date-time - example: '2022-05-05T18:28:54.535Z' subscription: type: string nullable: true format: date-time - example: '2022-06-09T22:58:05.576Z' - required: - - global - - subscription - title: SeenAt - example: - global: '2022-05-05T18:28:54.535Z' - subscription: null - Visit: + 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' + Identification: type: object additionalProperties: false + required: + - visitorId + - requestId + - browserDetails + - incognito + - ip + - timestamp + - time + - url + - tag + - visitorFound + - firstSeenAt + - lastSeenAt properties: + visitorId: + type: string + description: >- + String of 20 characters that uniquely identifies the visitor's + browser. requestId: - description: Unique identifier of the user's identification request. type: string - example: 1654815516083.OX6kx8 + description: Unique identifier of the user's request. browserDetails: $ref: '#/components/schemas/BrowserDetails' incognito: @@ -796,283 +913,293 @@ components: ip: type: string format: ipv4 - example: 8.8.8.8 + description: IP address of the requesting browser or bot. ipLocation: - type: object - additionalProperties: false - deprecated: true - 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. - properties: - accuracyRadius: - description: >- - The IP address is likely to be within this radius (in km) of the - specified location. - type: integer - minimum: 0 - 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: - type: object - additionalProperties: false - title: DeprecatedIPLocationCity - properties: - name: - type: string - country: - $ref: '#/components/schemas/Location' - continent: - $ref: '#/components/schemas/Location' - subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: DeprecatedIPLocation + $ref: '#/components/schemas/DeprecatedGeolocation' + linkedId: + type: string + description: A customer-provided id that was sent with the request. timestamp: description: Timestamp of the event with millisecond precision in Unix time. type: integer format: int64 - example: 1654815516086 time: - title: Time - description: Time expressed according to ISO 8601 in UTC format. type: string format: date-time - example: '2022-06-09T22:58:36Z' + 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: - description: Page URL from which the identification request was sent. type: string - example: https://some.website/path?query=params + description: Page URL from which the request was sent. tag: - description: >- - A customer-provided value or an object that was sent with - identification request. - type: object - additionalProperties: true - linkedId: - description: A customer-provided id that was sent with identification request. - type: string - example: someID + $ref: '#/components/schemas/Tag' confidence: - $ref: '#/components/schemas/Confidence' + $ref: '#/components/schemas/IdentificationConfidence' visitorFound: - description: Attribute represents if a visitor had been identified before. type: boolean + description: Attribute represents if a visitor had been identified before. firstSeenAt: - $ref: '#/components/schemas/SeenAt' + $ref: '#/components/schemas/IdentificationSeenAt' lastSeenAt: - $ref: '#/components/schemas/SeenAt' + $ref: '#/components/schemas/IdentificationSeenAt' + components: + $ref: '#/components/schemas/RawDeviceAttributes' + ErrorCode: + type: string + enum: + - RequestCannotBeParsed + - TokenRequired + - TokenNotFound + - SubscriptionNotActive + - WrongRegion + - FeatureNotEnabled + - 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. + * `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: - - browserDetails - - firstSeenAt - - incognito - - ip - - lastSeenAt - - requestId - - time - - timestamp - - url - - visitorFound - title: Visit - IdentificationError: - type: object - additionalProperties: false + - code + - message properties: code: - type: string - description: | - Error code: - * `429 Too Many Requests` - the limit on secret API key requests per second has been exceeded - * `Failed` - internal server error - enum: - - 429 Too Many Requests - - Failed - example: 429 Too Many Requests + $ref: '#/components/schemas/ErrorCode' message: type: string - example: too many requests - required: - - code - - message - BotdDetectionResult: + 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: - type: string - 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 - enum: - - notDetected - - good - - bad - example: bad + $ref: '#/components/schemas/BotdBotResult' type: type: string - example: selenium - required: - - result - BotdResult: + Botd: type: object - additionalProperties: false 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 format: ipv4 - example: 8.8.8.8 description: IP address of the requesting browser or bot. time: - title: Time + type: string + format: date-time 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 - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - url: - description: Page URL from which identification request was sent. - type: string - example: https://example.com/login + malicious. Otherwise, request replay attacks are possible. userAgent: type: string - example: >- - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 - (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 requestId: type: string - example: 1681392853693.lRiBBD - linkedId: - type: string - example: Automatic tests bot - bot: - $ref: '#/components/schemas/BotdDetectionResult' + 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: - - bot - - url - - ip - - time - - userAgent - - requestId - ProductError: + - 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: - code: - type: string - description: | - Error code: - * `TooManyRequests` - the limit on secret API key requests per second has been exceeded - * `Failed` - internal server error - enum: - - TooManyRequests - - Failed - example: TooManyRequests - message: - type: string - example: too many requests + data: + $ref: '#/components/schemas/RootApps' + error: + $ref: '#/components/schemas/Error' + Emulator: + type: object + additionalProperties: false required: - - code - - message - IPLocation: + - 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. - type: integer - minimum: 0 - example: 1000 latitude: type: number format: double minimum: -90 maximum: 90 - example: 37.75 longitude: type: number format: double minimum: -180 maximum: 180 - example: -97.82 postalCode: type: string - example: 130 00 timezone: type: string format: timezone - example: America/Chicago city: - type: object - additionalProperties: false - title: IPLocationCity - properties: - name: - type: string - example: Prague + $ref: '#/components/schemas/GeolocationCity' country: - $ref: '#/components/schemas/Location' + $ref: '#/components/schemas/GeolocationCountry' continent: - $ref: '#/components/schemas/Location' + $ref: '#/components/schemas/GeolocationContinent' subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: IPLocation - ASN: + $ref: '#/components/schemas/GeolocationSubdivisions' + IPInfoASN: type: object additionalProperties: false + required: + - asn + - name + - network properties: asn: type: string - example: '7922' - network: - type: string - example: 73.136.0.0/13 name: type: string - example: COMCAST-7922 - required: - - asn - - network - title: ASN - DataCenter: + network: + type: string + IPInfoDataCenter: type: object additionalProperties: false + required: + - result + - name properties: result: type: boolean name: type: string - example: DediPath + IPInfoV4: + type: object + additionalProperties: false required: - - result - title: DataCenter - IpInfoResult: + - 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 @@ -1080,362 +1207,414 @@ components: additionalProperties: false properties: v4: - type: object - additionalProperties: false - properties: - address: - type: string - format: ipv4 - example: 94.142.239.124 - geolocation: - $ref: '#/components/schemas/IPLocation' - asn: - $ref: '#/components/schemas/ASN' - datacenter: - $ref: '#/components/schemas/DataCenter' - required: - - address - - geolocation + $ref: '#/components/schemas/IPInfoV4' v6: - type: object - additionalProperties: false - properties: - address: - type: string - format: ipv6 - example: 2001:0db8:85a3:0000:0000:8a2e:0370:7334 - geolocation: - $ref: '#/components/schemas/IPLocation' - asn: - $ref: '#/components/schemas/ASN' - datacenter: - $ref: '#/components/schemas/DataCenter' - required: - - address - - geolocation - IncognitoResult: + $ref: '#/components/schemas/IPInfoV6' + ProductIPInfo: type: object additionalProperties: false properties: - result: - type: boolean - description: > - `true` if we detected incognito mode used in the browser, `false` - otherwise. - example: false - required: - - result - RootAppsResult: + data: + $ref: '#/components/schemas/IPInfo' + error: + $ref: '#/components/schemas/Error' + IPBlocklistDetails: 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. - example: false required: - - result - EmulatorResult: - type: object - additionalProperties: false + - emailSpam + - attackSource properties: - result: + emailSpam: 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. - example: false - required: - - result - ClonedAppResult: - type: object - additionalProperties: false - properties: - result: + description: IP address was part of a known email spam attack (SMTP). + attackSource: 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. - example: false - required: - - result - FactoryResetResult: + description: IP address was part of a known network attack (SSH/HTTPS). + IPBlocklist: type: object additionalProperties: false - properties: - 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. - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - timestamp: - 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. - type: integer - format: int64 - example: 1654815517198 required: - - time - - timestamp - JailbrokenResult: - type: object - additionalProperties: false + - result + - details 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. - example: false - required: - - result - FridaResult: + `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: - 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. - example: false - required: - - result - IpBlockListResult: + data: + $ref: '#/components/schemas/IPBlocklist' + error: + $ref: '#/components/schemas/Error' + Tor: 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. - example: false - details: - type: object - additionalProperties: false - properties: - emailSpam: - type: boolean - description: IP address was part of a known email spam attack (SMTP). - example: false - attackSource: - type: boolean - description: IP address was part of a known network attack (SSH/HTTPS). - example: false - required: - - emailSpam - - attackSource required: - result - - details - TorResult: - type: object - additionalProperties: false properties: result: type: boolean description: > `true` if the request IP address is a known tor exit node, `false` otherwise. - example: false - required: - - result - PrivacySettingsResult: + ProductTor: 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`. - example: false - required: - - result - VirtualMachineResult: + 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 properties: - result: + timezoneMismatch: type: boolean - description: > - `true` if the request came from a browser running inside a virtual - machine (e.g. VMWare), `false` otherwise. - example: false - required: - - result - VpnResult: + 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. + 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. - example: false + confidence: + $ref: '#/components/schemas/VPNConfidence' originTimezone: type: string description: Local timezone which is used in timezoneMismatch method. - example: Europe/Berlin originCountry: type: string description: >- Country of the request (only for Android SDK version >= 2.4.0, ISO 3166 format or unknown). - example: unknown methods: - type: object - additionalProperties: false - properties: - timezoneMismatch: - type: boolean - description: >- - The browser timezone doesn't match the timezone inferred from - the request IP address. - example: false - publicVPN: - type: boolean - description: >- - Request IP address is owned and used by a public VPN service - provider. - example: false - 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. - example: false - osMismatch: - type: boolean - description: >- - The browser runs on a different operating system than the - operating system inferred from the request network signature. - example: false - required: - - timezoneMismatch - - publicVPN - - auxiliaryMobile - - osMismatch - confidence: - 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. - example: low - required: - - result - - originTimezone - - methods - - confidence - ProxyResult: + $ref: '#/components/schemas/VPNMethods' + ProductVPN: + type: object + additionalProperties: false + properties: + data: + $ref: '#/components/schemas/VPN' + error: + $ref: '#/components/schemas/Error' + Proxy: type: object additionalProperties: false + required: + - result properties: result: type: boolean description: > `true` if the request IP address is used by a public proxy provider, `false` otherwise. - example: false - required: - - result - TamperingResult: + 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: >- - Flag indicating browser tampering was detected. This happens when - either of these conditions is true: - * There are inconsistencies in the browser configuration that cross our internal tampering thresholds (indicated by `anomalyScore`). - * The browser signature resembles one of "anti-detect" browsers specifically designed to evade identification and fingerprinting, for example, Incognition (indicated by `antiDetectBrowser`). - example: false + 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 + - anomalyScore + - antiDetectBrowser + properties: + result: + type: boolean + description: > + Flag indicating browser tampering was detected. This happens when + either of these conditions is true: + * There are inconsistencies in the browser configuration that cross our internal tampering thresholds (indicated by `anomalyScore`). + * The browser signature resembles one of "anti-detect" browsers specifically designed to evade identification and fingerprinting, for example, Incognition (indicated by `antiDetectBrowser`). anomalyScore: type: number - description: >- - Confidence score (`0.0 - 1.0`) for tampering detection. Values above - `0.5` indicate that there was a tampering attempt. Values below - `0.5` indicate genuine browsers. - example: 0 + format: double minimum: 0 maximum: 1 + description: | + Confidence score (`0.0 - 1.0`) for tampering detection: + * Values above `0.5` indicate that there was a tampering attempt. + * Values below `0.5` indicate genuine browsers. antiDetectBrowser: type: boolean description: >- Is `true` if the identified browser resembles one of "anti-detect" - browsers, for example, Incognition. Anti-detect browsers try to + browsers, for example, Incognition. Anti-detect browsers try to evade identification by masking or manipulating their fingerprint to imitate legitimate browser configurations. - example: false + ProductTampering: + type: object + additionalProperties: false + properties: + data: + $ref: '#/components/schemas/Tampering' + error: + $ref: '#/components/schemas/Error' + ClonedApp: + type: object + additionalProperties: false required: - result - - anomalyScore - - antiDetectBrowser - HighActivityResult: + 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://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. + 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: >- - Flag indicating whether the request came from a high activity - visitor. - example: false - dailyRequests: - type: number - description: Number of requests from the same visitor in the previous day. - example: 10 - minimum: 1 + 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. + 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 - LocationSpoofingResult: + 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' + 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. - example: false - required: - - result - SuspectScoreResult: + 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 @@ -1446,66 +1625,47 @@ components: 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 - example: 0 - required: - - result - RawDeviceAttributesResult: + ProductSuspectScore: 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: - type: object - properties: - error: - properties: - name: - title: error.name - type: string - message: - title: error.message - type: string - required: - - name - - message - title: error - type: object - value: - title: value - RemoteControlResult: + additionalProperties: false + properties: + data: + $ref: '#/components/schemas/SuspectScore' + error: + $ref: '#/components/schemas/Error' + RemoteControl: type: object 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. - example: false - required: - - result - VelocityIntervalResult: + ProductRemoteControl: + type: object + 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 - example: 1 1h: type: integer - example: 1 24h: type: integer description: > @@ -1514,17 +1674,13 @@ components: `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. - example: 1 - required: - - 5m - - 1h - VelocityIntervals: + VelocityData: type: object additionalProperties: false properties: intervals: - $ref: '#/components/schemas/VelocityIntervalResult' - VelocityResult: + $ref: '#/components/schemas/VelocityIntervals' + Velocity: type: object description: > Sums key data points for a specific `visitorId`, `ipAddress` and @@ -1533,15 +1689,16 @@ components: intervals: 5 minutes, 1 hour, and 24 hours as follows: - - Number of identification events associated with the visitor ID. + - Number of distinct IP addresses associated to the visitor ID. - Number of distinct linked IDs associated with the visitor ID. - - Number of distinct IP addresses associated to the visitor ID. - - Number of distinct countries associated with the visitor ID. - - Number of events associated for the detected IP address. + - 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. @@ -1559,42 +1716,57 @@ components: hours (`events.intervals.['24h']`) is higher than 20.000. additionalProperties: false - properties: - events: - $ref: '#/components/schemas/VelocityIntervals' - distinctLinkedId: - $ref: '#/components/schemas/VelocityIntervals' - distinctIp: - $ref: '#/components/schemas/VelocityIntervals' - distinctCountry: - $ref: '#/components/schemas/VelocityIntervals' - ipEvents: - $ref: '#/components/schemas/VelocityIntervals' - distinctIpByLinkedId: - $ref: '#/components/schemas/VelocityIntervals' - distinctVisitorIdByLinkedId: - $ref: '#/components/schemas/VelocityIntervals' required: - - events - - distinctLinkedId - distinctIp + - distinctLinkedId - distinctCountry + - events - ipEvents - distinctIpByLinkedId - distinctVisitorIdByLinkedId - DeveloperToolsResult: + 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 is Chrome with DevTools open or Firefox with Developer Tools open, `false` otherwise. - example: false - required: - - result - ProductsResponse: + ProductDeveloperTools: + type: object + additionalProperties: false + properties: + data: + $ref: '#/components/schemas/DeveloperTools' + error: + $ref: '#/components/schemas/Error' + Products: type: object description: >- Contains all information about the request identified by `requestId`, @@ -1602,897 +1774,614 @@ components: additionalProperties: false properties: identification: - type: object - additionalProperties: false - title: ProductsResponseIdentification - properties: - data: - title: ProductsResponseIdentificationData - type: object - properties: - requestId: - description: Unique identifier of the user's identification request. - type: string - example: 1654815516083.OX6kx8 - browserDetails: - $ref: '#/components/schemas/BrowserDetails' - incognito: - description: Flag if user used incognito session. - type: boolean - ip: - type: string - format: ipv4 - example: 8.8.8.8 - ipLocation: - type: object - additionalProperties: false - deprecated: true - 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. - properties: - accuracyRadius: - description: >- - The IP address is likely to be within this radius (in - km) of the specified location. - type: integer - minimum: 0 - 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: - type: object - additionalProperties: false - title: DeprecatedIPLocationCity - properties: - name: - type: string - country: - $ref: '#/components/schemas/Location' - continent: - $ref: '#/components/schemas/Location' - subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: DeprecatedIPLocation - timestamp: - description: >- - Timestamp of the event with millisecond precision in Unix - time. - type: integer - format: int64 - example: 1654815516086 - time: - title: Time - description: Time expressed according to ISO 8601 in UTC format. - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - url: - description: Page URL from which the identification request was sent. - type: string - example: https://some.website/path?query=params - tag: - description: >- - A customer-provided value or an object that was sent with - identification request. - type: object - additionalProperties: true - linkedId: - description: >- - A customer-provided id that was sent with identification - request. - type: string - example: someID - confidence: - $ref: '#/components/schemas/Confidence' - visitorFound: - description: >- - Attribute represents if a visitor had been identified - before. - type: boolean - firstSeenAt: - $ref: '#/components/schemas/SeenAt' - lastSeenAt: - $ref: '#/components/schemas/SeenAt' - visitorId: - type: string - description: > - String of 20 characters that uniquely identifies the - visitor's browser. - example: - - Ibk1527CUFmcnjLwIs4A - additionalProperties: false - required: - - browserDetails - - firstSeenAt - - incognito - - ip - - lastSeenAt - - requestId - - time - - timestamp - - url - - visitorFound - - visitorId - - tag - error: - $ref: '#/components/schemas/IdentificationError' + $ref: '#/components/schemas/ProductIdentification' botd: - title: ProductsResponseBotd - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/BotdResult' - error: - $ref: '#/components/schemas/ProductError' - ipInfo: - title: SignalResponseIpInfo - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/IpInfoResult' - error: - $ref: '#/components/schemas/ProductError' - incognito: - title: SignalResponseIncognito - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/IncognitoResult' - error: - $ref: '#/components/schemas/IdentificationError' + $ref: '#/components/schemas/ProductBotd' rootApps: - title: SignalResponseRootApps - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/RootAppsResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductRootApps' emulator: - title: SignalResponseEmulator - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/EmulatorResult' - error: - $ref: '#/components/schemas/ProductError' + $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: - title: SignalResponseClonedApp - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/ClonedAppResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductClonedApp' factoryReset: - title: SignalResponseFactoryReset - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/FactoryResetResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductFactoryReset' jailbroken: - title: SignalResponseJailbroken - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/JailbrokenResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductJailbroken' frida: - title: SignalResponseFrida - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/FridaResult' - error: - $ref: '#/components/schemas/ProductError' - ipBlocklist: - title: SignalResponseIpBlocklist - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/IpBlockListResult' - error: - $ref: '#/components/schemas/ProductError' - tor: - title: SignalResponseTor - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/TorResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductFrida' privacySettings: - title: SignalResponsePrivacySettings - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/PrivacySettingsResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductPrivacySettings' virtualMachine: - title: SignalResponseVirtualMachine - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/VirtualMachineResult' - error: - $ref: '#/components/schemas/ProductError' - vpn: - title: SignalResponseVpn - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/VpnResult' - error: - $ref: '#/components/schemas/ProductError' - proxy: - title: SignalResponseProxy - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/ProxyResult' - error: - $ref: '#/components/schemas/ProductError' - tampering: - title: SignalResponseTampering - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/TamperingResult' - error: - $ref: '#/components/schemas/IdentificationError' + $ref: '#/components/schemas/ProductVirtualMachine' + rawDeviceAttributes: + $ref: '#/components/schemas/ProductRawDeviceAttributes' highActivity: - title: SignalResponseHighActivity - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/HighActivityResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductHighActivity' locationSpoofing: - title: SignalResponseLocationSpoofing - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/LocationSpoofingResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductLocationSpoofing' suspectScore: - title: SignalResponseSuspectScore - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/SuspectScoreResult' - error: - $ref: '#/components/schemas/ProductError' - rawDeviceAttributes: - title: SignalResponseRawDeviceAttributes - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/RawDeviceAttributesResult' - error: - $ref: '#/components/schemas/IdentificationError' + $ref: '#/components/schemas/ProductSuspectScore' remoteControl: - title: SignalResponseRemoteControl - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/RemoteControlResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductRemoteControl' velocity: - title: SignalResponseVelocity - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/VelocityResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductVelocity' developerTools: - title: SignalResponseDeveloperTools - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/DeveloperToolsResult' - error: - $ref: '#/components/schemas/ProductError' - EventResponse: + $ref: '#/components/schemas/ProductDeveloperTools' + EventsGetResponse: + type: object description: >- Contains results from all activated products - Fingerprint Pro, Bot Detection, and others. - type: object additionalProperties: false - properties: - products: - $ref: '#/components/schemas/ProductsResponse' - error: - $ref: '#/components/schemas/ProductError' required: - products - ErrorCommon403Response: - type: object - additionalProperties: false - properties: - error: - type: object - additionalProperties: false - title: Common403ErrorResponse - properties: - code: - type: string - description: | - Error code: - * `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 - enum: - - TokenRequired - - TokenNotFound - - SubscriptionNotActive - - WrongRegion - - FeatureNotEnabled - example: TokenRequired - message: - type: string - example: secret key is required - required: - - code - - message - ErrorEvent404Response: + properties: + products: + $ref: '#/components/schemas/Products' + ErrorResponse: type: object additionalProperties: false + required: + - error properties: error: - type: object - additionalProperties: false - title: ErrorEvent404ResponseError - properties: - code: - type: string - description: | - Error code: - * `RequestNotFound` - The specified request ID was not found. It never existed, expired, or it has been deleted. - enum: - - RequestNotFound - example: RequestNotFound - message: - type: string - example: request id is not found - required: - - code - - message - EventUpdateRequest: + $ref: '#/components/schemas/Error' + EventsUpdateRequest: type: object properties: linkedId: type: string description: LinkedID value to assign to the existing event tag: - type: object - description: >- - Full `tag` value to be set to the existing event. Replaces any - existing `tag` payload completely. + $ref: '#/components/schemas/Tag' suspect: type: boolean description: Suspect flag indicating observed suspicious or fraudulent event - ErrorUpdateEvent400Response: - type: object - additionalProperties: false - properties: - error: - type: object - additionalProperties: false - title: ErrorUpdateEvent400ResponseError - properties: - code: - type: string - description: > - Error code: * `RequestCannotBeParsed` - the JSON content of the - request contains some errors that prevented us from parsing it - (wrong type/surpassed limits) * `Failed` - the event is more - than 10 days old and cannot be updated - enum: - - RequestCannotBeParsed - - Failed - example: RequestCannotBeParsed - message: - type: string - description: Details about the underlying issue with the input payload - example: suspect flag must be a boolean - required: - - code - - message - ErrorUpdateEvent409Response: + Visit: type: object additionalProperties: false + required: + - requestId + - browserDetails + - incognito + - ip + - timestamp + - time + - url + - tag + - visitorFound + - firstSeenAt + - lastSeenAt properties: - error: - type: object - additionalProperties: false - title: ErrorUpdateEvent409ResponseError - properties: - code: - type: string - description: > - Error code: * `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. - enum: - - StateNotReady - example: StateNotReady - message: - type: string - example: resource is not mutable yet, try again - required: - - code - - message - Response: + 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 + format: ipv4 + 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 + 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: >- + Pagination-related fields `lastTimestamp` and `paginationKey` are + included if you use a pagination parameter like `limit` or `before` and + there is more data available on the next page. additionalProperties: false + required: + - visitorId + - visits properties: visitorId: type: string visits: type: array items: - title: ResponseVisits - type: object - properties: - requestId: - description: Unique identifier of the user's identification request. - type: string - example: 1654815516083.OX6kx8 - browserDetails: - $ref: '#/components/schemas/BrowserDetails' - incognito: - description: Flag if user used incognito session. - type: boolean - ip: - type: string - format: ipv4 - example: 8.8.8.8 - ipLocation: - type: object - additionalProperties: false - deprecated: true - 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. - properties: - accuracyRadius: - description: >- - The IP address is likely to be within this radius (in km) - of the specified location. - type: integer - minimum: 0 - 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: - type: object - additionalProperties: false - title: DeprecatedIPLocationCity - properties: - name: - type: string - country: - $ref: '#/components/schemas/Location' - continent: - $ref: '#/components/schemas/Location' - subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: DeprecatedIPLocation - timestamp: - description: >- - Timestamp of the event with millisecond precision in Unix - time. - type: integer - format: int64 - example: 1654815516086 - time: - title: Time - description: Time expressed according to ISO 8601 in UTC format. - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - url: - description: Page URL from which the identification request was sent. - type: string - example: https://some.website/path?query=params - tag: - description: >- - A customer-provided value or an object that was sent with - identification request. - type: object - additionalProperties: true - linkedId: - description: >- - A customer-provided id that was sent with identification - request. - type: string - example: someID - confidence: - $ref: '#/components/schemas/Confidence' - visitorFound: - description: Attribute represents if a visitor had been identified before. - type: boolean - firstSeenAt: - $ref: '#/components/schemas/SeenAt' - lastSeenAt: - $ref: '#/components/schemas/SeenAt' - additionalProperties: false - required: - - browserDetails - - firstSeenAt - - incognito - - ip - - lastSeenAt - - requestId - - time - - timestamp - - url - - visitorFound - - tag + $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. - type: integer - format: int64 - example: 1654815517198 paginationKey: + type: string description: >- Request ID of the last visit in the current page of results. Use this value in the following request as the `paginationKey` parameter to get the next page of results. - type: string - example: 1654815517198.azN4IZ + ErrorPlainResponse: + type: object + additionalProperties: false required: - - visitorId - - visits - title: PaginatedResponse + - error + properties: + error: + type: string + 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: >- - Fields `lastTimestamp` and `paginationKey` added when `limit` or - `before` parameter provided and there is more data to show - ErrorVisits403: + 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: - error: + 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' + originTimezone: type: string - description: Error text. - example: Forbidden (HTTP 403) - required: - - error - TooManyRequestsResponse: + 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: - error: + result: + type: boolean + description: > + `true` if the request IP address is used by a public proxy provider, + `false` otherwise. + WebhookTampering: + type: object + additionalProperties: false + properties: + result: + type: boolean + description: > + Flag indicating browser tampering was detected. This happens when + either of these conditions is true: + * There are inconsistencies in the browser configuration that cross our internal tampering thresholds (indicated by `anomalyScore`). + * The browser signature resembles one of "anti-detect" browsers specifically designed to evade identification and fingerprinting, for example, Incognition (indicated by `antiDetectBrowser`). + anomalyScore: + type: number + format: double + minimum: 0 + maximum: 1 + description: | + Confidence score (`0.0 - 1.0`) for tampering detection: + * Values above `0.5` indicate that there was a tampering attempt + * Values below `0.5` indicate genuine browsers. + antiDetectBrowser: + type: boolean + description: >- + Is `true` if the identified browser resembles one of "anti-detect" + browsers, for example, Incognition. Anti-detect browsers try to + evade identification by masking or manipulating their fingerprint to + imitate legitimate browser configurations. + 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 - description: Error text. - example: request throttled + 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. + 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. + 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: - - error - ErrorVisitor400Response: + - 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: - error: - type: object - additionalProperties: false - properties: - code: - type: string - description: > - Error code: * `RequestCannotBeParsed` - The visitor ID parameter - is missing or in the wrong format. - enum: - - RequestCannotBeParsed - example: RequestCannotBeParsed - message: - type: string - example: invalid visitor id - required: - - code - - message - ErrorVisitor404Response: + result: + type: boolean + description: >- + Flag indicating whether the request came from a mobile device with + location spoofing enabled. + WebhookSuspectScore: type: object additionalProperties: false properties: - error: - type: object - additionalProperties: false - title: ErrorVisitor404ResponseError - properties: - code: - type: string - description: > - Error code: * `VisitorNotFound` - The specified visitor ID was - not found. It never existed or it may have already been deleted. - enum: - - VisitorNotFound - example: VisitorNotFound - message: - type: string - example: visitor not found - required: - - code - - message - ErrorCommon429Response: + 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 + WebhookRemoteControl: type: object additionalProperties: false properties: - error: - type: object - additionalProperties: false - properties: - code: - type: string - description: | - Error code: * `TooManyRequests` - The request is throttled. - enum: - - TooManyRequests - example: TooManyRequests - message: - type: string - example: request throttled - required: - - code - - message - WebhookVisit: + 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 is Chrome with DevTools open or Firefox with + Developer Tools open, `false` otherwise. + Webhook: + type: object + required: + - requestId + - url + - ip + - time + - timestamp 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 + format: ipv4 + description: IP address of the requesting browser or bot. + tag: + $ref: '#/components/schemas/Tag' + time: + type: string + format: date-time + 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 - example: 3HNey93AkBW6CRbxV6xP + description: >- + String of 20 characters that uniquely identifies the visitor's + browser. + 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 - example: https://google.com?search=banking+services + components: + $ref: '#/components/schemas/RawDeviceAttributes' + bot: + $ref: '#/components/schemas/BotdBot' userAgent: type: string - example: >- - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 - (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 - bot: - $ref: '#/components/schemas/BotdDetectionResult' - ipInfo: - $ref: '#/components/schemas/IpInfoResult' - incognito: - description: Flag if user used incognito session. - type: boolean rootApps: - $ref: '#/components/schemas/RootAppsResult' + $ref: '#/components/schemas/WebhookRootApps' emulator: - $ref: '#/components/schemas/EmulatorResult' + $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/ClonedAppResult' + $ref: '#/components/schemas/WebhookClonedApp' factoryReset: - $ref: '#/components/schemas/FactoryResetResult' + $ref: '#/components/schemas/WebhookFactoryReset' jailbroken: - $ref: '#/components/schemas/JailbrokenResult' + $ref: '#/components/schemas/WebhookJailbroken' frida: - $ref: '#/components/schemas/FridaResult' - ipBlocklist: - $ref: '#/components/schemas/IpBlockListResult' - tor: - $ref: '#/components/schemas/TorResult' + $ref: '#/components/schemas/WebhookFrida' privacySettings: - $ref: '#/components/schemas/PrivacySettingsResult' + $ref: '#/components/schemas/WebhookPrivacySettings' virtualMachine: - $ref: '#/components/schemas/VirtualMachineResult' - vpn: - $ref: '#/components/schemas/VpnResult' - proxy: - $ref: '#/components/schemas/ProxyResult' - tampering: - $ref: '#/components/schemas/TamperingResult' + $ref: '#/components/schemas/WebhookVirtualMachine' rawDeviceAttributes: - $ref: '#/components/schemas/RawDeviceAttributesResult' + $ref: '#/components/schemas/WebhookRawDeviceAttributes' highActivity: - $ref: '#/components/schemas/HighActivityResult' + $ref: '#/components/schemas/WebhookHighActivity' locationSpoofing: - $ref: '#/components/schemas/LocationSpoofingResult' + $ref: '#/components/schemas/WebhookLocationSpoofing' suspectScore: - $ref: '#/components/schemas/SuspectScoreResult' + $ref: '#/components/schemas/WebhookSuspectScore' remoteControl: - $ref: '#/components/schemas/RemoteControlResult' + $ref: '#/components/schemas/WebhookRemoteControl' velocity: - $ref: '#/components/schemas/VelocityResult' + $ref: '#/components/schemas/WebhookVelocity' developerTools: - $ref: '#/components/schemas/DeveloperToolsResult' - requestId: - description: Unique identifier of the user's identification request. - type: string - example: 1654815516083.OX6kx8 - browserDetails: - $ref: '#/components/schemas/BrowserDetails' - ip: - type: string - format: ipv4 - example: 8.8.8.8 - ipLocation: - type: object - additionalProperties: false - deprecated: true - 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. - properties: - accuracyRadius: - description: >- - The IP address is likely to be within this radius (in km) of the - specified location. - type: integer - minimum: 0 - 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: - type: object - additionalProperties: false - title: DeprecatedIPLocationCity - properties: - name: - type: string - country: - $ref: '#/components/schemas/Location' - continent: - $ref: '#/components/schemas/Location' - subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: DeprecatedIPLocation - timestamp: - description: Timestamp of the event with millisecond precision in Unix time. - type: integer - format: int64 - example: 1654815516086 - time: - title: Time - description: Time expressed according to ISO 8601 in UTC format. - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - url: - description: Page URL from which the identification request was sent. - type: string - example: https://some.website/path?query=params - tag: - description: >- - A customer-provided value or an object that was sent with - identification request. - type: object - additionalProperties: true - linkedId: - description: A customer-provided id that was sent with identification request. - type: string - example: someID - confidence: - $ref: '#/components/schemas/Confidence' - visitorFound: - description: Attribute represents if a visitor had been identified before. - type: boolean - firstSeenAt: - $ref: '#/components/schemas/SeenAt' - lastSeenAt: - $ref: '#/components/schemas/SeenAt' - additionalProperties: false - required: - - visitorId - - browserDetails - - firstSeenAt - - incognito - - ip - - lastSeenAt - - requestId - - time - - timestamp - - url - - visitorFound + $ref: '#/components/schemas/WebhookDeveloperTools' 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. - type: string - example: Ibk1527CUFmcnjLwIs4A - required: - - visitorId RelatedVisitorsResponse: type: object additionalProperties: false + required: + - relatedVisitors properties: relatedVisitors: type: array items: $ref: '#/components/schemas/RelatedVisitor' - required: - - relatedVisitors diff --git a/schemas/fingerprint-server-api.yaml b/schemas/fingerprint-server-api.yaml index a8ad9e61..bdc4ab8d 100644 --- a/schemas/fingerprint-server-api.yaml +++ b/schemas/fingerprint-server-api.yaml @@ -53,22 +53,22 @@ paths: parameters: - name: request_id in: path - description: >- - The unique - [identifier](https://dev.fingerprint.com/docs/js-agent#requestid) of - each identification request. required: true schema: type: string + description: >- + The unique + [identifier](https://dev.fingerprint.com/reference/get-function#requestid) + of each identification request. responses: '200': - description: OK + description: OK. content: application/json: schema: - $ref: '#/components/schemas/EventResponse' + $ref: '#/components/schemas/EventsGetResponse' examples: - fullResponse: + 200-full: summary: Example response value: products: @@ -201,6 +201,7 @@ paths: vpn: data: result: false + confidence: high originTimezone: Europe/Berlin originCountry: unknown methods: @@ -208,7 +209,6 @@ paths: publicVPN: false auxiliaryMobile: false osMismatch: false - confidence: high proxy: data: result: false @@ -310,14 +310,14 @@ paths: developerTools: data: result: false - allErrorsResponse: + 200-all-errors: summary: All failed signals value: products: identification: error: code: Failed - message: failed + message: internal server error botd: error: code: Failed @@ -416,61 +416,29 @@ paths: error: code: Failed message: internal server error - withBotdError: - summary: BotD error + 200-identification-error: + summary: Identification error value: products: identification: - data: - visitorId: Ibk1527CUFmcnjLwIs4A9 - requestId: 0KSh65EnVoB85JBmloQK - incognito: true - linkedId: somelinkedId - time: '2019-05-21T16:40:13Z' - tag: {} - timestamp: 1582299576512 - url: https://www.example.com/login - ip: 61.127.217.15 - ipLocation: - accuracyRadius: 10 - latitude: 49.982 - longitude: 36.2566 - postalCode: '61202' - timezone: Europe/Dusseldorf - city: - name: Dusseldorf - continent: - code: EU - name: Europe - country: - code: DE - name: Germany - 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: true - firstSeenAt: - global: '2022-03-16T11:26:45.362Z' - subscription: '2022-03-16T11:31:01.101Z' - lastSeenAt: - global: '2022-03-16T11:28:34.023Z' - subscription: null - botd: error: code: Failed message: internal server error - withBotdTooManyRequestsError: - summary: BotD too many requests error + botd: + data: + bot: + result: bad + type: headlessChrome + url: https://example.com/login + ip: 94.60.143.223 + time: '2024-02-23T10:20:25.287Z' + userAgent: >- + Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) + AppleWebKit/537.36 (KHTML, like Gecko) + HeadlessChrome/121.0.6167.57 Safari/537.36 + requestId: 1708683625245.tuJ4nD + 200-botd-error: + summary: BotD error value: products: identification: @@ -479,8 +447,8 @@ paths: requestId: 0KSh65EnVoB85JBmloQK incognito: true linkedId: somelinkedId - tag: {} time: '2019-05-21T16:40:13Z' + tag: {} timestamp: 1582299576512 url: https://www.example.com/login ip: 61.127.217.15 @@ -519,32 +487,11 @@ paths: global: '2022-03-16T11:28:34.023Z' subscription: null botd: - error: - code: TooManyRequests - message: too many requests - withIdentificationError: - summary: Identification error - value: - products: - identification: error: code: Failed - message: failed - botd: - data: - bot: - result: bad - type: headlessChrome - url: https://example.com/login - ip: 94.60.143.223 - time: '2024-02-23T10:20:25.287Z' - userAgent: >- - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) - AppleWebKit/537.36 (KHTML, like Gecko) - HeadlessChrome/121.0.6167.57 Safari/537.36 - requestId: 1708683625245.tuJ4nD - withIdentificationTooManyRequestsError: - summary: Identification too many requests error + message: internal server error + 200-too-many-requests-error: + summary: Too many requests error value: products: identification: @@ -552,40 +499,49 @@ paths: code: 429 Too Many Requests message: too many requests botd: - data: - bot: - result: bad - type: headlessChrome - url: https://example.com/login - ip: 94.60.143.223 - time: '2024-02-23T10:20:25.287Z' - userAgent: >- - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) - AppleWebKit/537.36 (KHTML, like Gecko) - HeadlessChrome/121.0.6167.57 Safari/537.36 - requestId: 1708683625245.tuJ4nD + error: + code: TooManyRequests + message: too many requests '403': - description: Forbidden + description: Forbidden. Access to this API is denied. content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon403Response' + $ref: '#/components/schemas/ErrorResponse' examples: - example: - summary: Forbidden + 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 is different from the + region, the calling application is configured with. + value: + error: + code: WrongRegion + message: wrong region '404': - description: Not found + description: >- + Not found. The request ID cannot be found in this application's + data. content: application/json: schema: - $ref: '#/components/schemas/ErrorEvent404Response' + $ref: '#/components/schemas/ErrorResponse' examples: - example: - summary: Not found + 404-request-not-found: + summary: Error response when the provided request ID does not exist. value: error: code: RequestNotFound @@ -610,69 +566,89 @@ paths: parameters: - name: request_id in: path - description: >- - The unique event - [identifier](https://dev.fingerprint.com/docs/js-agent#requestid). required: true schema: type: string + description: >- + The unique event + [identifier](https://dev.fingerprint.com/reference/get-function#requestid). requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/EventUpdateRequest' + $ref: '#/components/schemas/EventsUpdateRequest' responses: '200': - description: OK + description: OK. '400': - description: Bad request + description: Bad request. The request payload is not valid. content: application/json: schema: - $ref: '#/components/schemas/ErrorUpdateEvent400Response' + $ref: '#/components/schemas/ErrorResponse' examples: example: - summary: Example response + summary: >- + Error response when the specified request payload is not + valid and cannot be parsed. value: error: code: RequestCannotBeParsed message: request body is not valid '403': - description: Forbidden + description: Forbidden. Access to this API is denied. content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon403Response' + $ref: '#/components/schemas/ErrorResponse' examples: - example: - summary: Example response + 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 is different from the + region, the calling application is configured with. + value: + error: + code: WrongRegion + message: wrong region '404': - description: Not found + description: >- + Not found. The request ID cannot be found in this application's + data. content: application/json: schema: - $ref: '#/components/schemas/ErrorEvent404Response' + $ref: '#/components/schemas/ErrorResponse' examples: - example: - summary: Example response + 404-request-not-found: + summary: Error response when the provided request ID does not exist. value: error: code: RequestNotFound message: request id is not found '409': - description: Conflict + description: Conflict. The event is not mutable yet. content: application/json: schema: - $ref: '#/components/schemas/ErrorUpdateEvent409Response' + $ref: '#/components/schemas/ErrorResponse' examples: example: - summary: Example response + summary: Error response when the event is not mutable yet. value: error: code: StateNotReady @@ -699,16 +675,18 @@ paths: response is received. parameters: - name: visitor_id - description: >- - Unique [visitor - identifier](https://dev.fingerprint.com/docs/js-agent#visitorid) - issued by Fingerprint Pro. in: path required: true schema: type: string - example: uYIm7Ksp5rf00SllPhFp + description: >- + Unique [visitor + identifier](https://dev.fingerprint.com/reference/get-function#visitorid) + issued by Fingerprint Pro. - name: request_id + in: query + schema: + type: string description: > Filter visits by `requestId`. @@ -716,27 +694,29 @@ paths: Every identification request has a unique identifier associated with it called `requestId`. This identifier is returned to the client in the identification - [result](https://dev.fingerprint.com/docs/js-agent#requestid). When - you filter visits by `requestId`, only one visit will be returned. + [result](https://dev.fingerprint.com/reference/get-function#requestid). + When you filter visits by `requestId`, only one visit will be + returned. + - name: linked_id in: query schema: type: string - - name: linked_id description: > Filter visits by your custom identifier. You can use - [`linkedId`](https://dev.fingerprint.com/docs/js-agent#linkedid) to - associate identification requests with your own identifier, for + [`linkedId`](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: limit in: query schema: - type: string - required: false - - name: limit + type: integer + format: int32 + minimum: 0 description: > Limit scanned results. @@ -749,12 +729,10 @@ paths: By default, the most recent 100 visits are scanned, the maximum is 500. + - name: paginationKey in: query schema: - type: integer - format: int32 - minimum: 0 - - name: paginationKey + type: string description: > Use `paginationKey` to get the next page of results. @@ -779,28 +757,25 @@ paths: get less visits than the `limit` you specified with more available on the next page. When there are no more results available for scanning, the `paginationKey` attribute is not returned. - in: query - schema: - type: string - required: false - name: before - description: > - ⚠️ Deprecated pagination method, please use `paginationKey` instead. - Timestamp (in milliseconds since epoch) used to paginate results. 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. responses: '200': - description: OK + description: OK. content: application/json: schema: - $ref: '#/components/schemas/Response' + $ref: '#/components/schemas/VisitorsGetResponse' examples: - limit1: + 200-limit-1: summary: Example response with limit=1 value: visitorId: AcxioeQKffpXF8iGQK3P @@ -817,7 +792,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 82.118.30.68 ipLocation: @@ -852,7 +826,7 @@ paths: subscription: '2022-06-16T10:03:00.912Z' lastTimestamp: 1655373953086 paginationKey: 1655373953086.DDlfmP - limit500: + 200-limit-500: summary: Example response with limit=500 value: visitorId: AcxioeQKffpXF8iGQK3P @@ -869,7 +843,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 188.242.36.107 ipLocation: @@ -914,7 +887,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 82.118.30.62 ipLocation: @@ -959,7 +931,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 82.118.30.68 ipLocation: @@ -1004,7 +975,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 82.118.30.91 ipLocation: @@ -1049,7 +1019,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 188.242.36.107 ipLocation: @@ -1094,7 +1063,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.137 timestamp: 1655106799878 @@ -1122,7 +1090,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.157 ipLocation: @@ -1154,7 +1121,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 188.242.36.107 ipLocation: @@ -1184,7 +1150,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 188.242.36.107 ipLocation: @@ -1229,7 +1194,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 188.242.36.107 ipLocation: @@ -1274,7 +1238,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1318,7 +1281,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1362,7 +1324,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1406,7 +1367,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.64 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1450,7 +1410,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1494,7 +1453,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1538,7 +1496,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1582,7 +1539,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1626,7 +1582,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1670,7 +1625,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36 - botProbability: 0 incognito: false ip: 217.150.54.233 ipLocation: @@ -1715,7 +1669,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36 - botProbability: 0 incognito: true ip: 217.150.54.233 ipLocation: @@ -1760,7 +1713,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36 - botProbability: 0 incognito: false ip: 217.150.54.233 ipLocation: @@ -1805,7 +1757,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1849,7 +1800,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1893,7 +1843,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.157 ipLocation: @@ -1937,7 +1886,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 89.38.224.165 ipLocation: @@ -1981,7 +1929,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 188.242.36.107 ipLocation: @@ -2026,7 +1973,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 84.247.59.113 ipLocation: @@ -2071,7 +2017,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 84.247.59.113 ipLocation: @@ -2116,7 +2061,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 84.247.59.146 ipLocation: @@ -2161,7 +2105,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 84.247.59.146 ipLocation: @@ -2206,7 +2149,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.105 ipLocation: @@ -2245,7 +2187,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.99 ipLocation: @@ -2284,7 +2225,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.99 ipLocation: @@ -2323,7 +2263,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.96 ipLocation: @@ -2362,7 +2301,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.96 ipLocation: @@ -2401,7 +2339,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 188.242.36.107 ipLocation: @@ -2446,7 +2383,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.227 ipLocation: @@ -2485,7 +2421,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.89 ipLocation: @@ -2524,7 +2459,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.111 ipLocation: @@ -2563,7 +2497,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.111 ipLocation: @@ -2602,7 +2535,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.111 ipLocation: @@ -2641,7 +2573,6 @@ paths: Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.198 ipLocation: @@ -2680,7 +2611,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.198 ipLocation: @@ -2719,7 +2649,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.206 ipLocation: @@ -2758,7 +2687,6 @@ paths: Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.204 ipLocation: @@ -2797,7 +2725,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.204 ipLocation: @@ -2836,7 +2763,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.204 ipLocation: @@ -2875,7 +2801,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.204 ipLocation: @@ -2914,7 +2839,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.172 ipLocation: @@ -2953,7 +2877,6 @@ paths: Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.210 ipLocation: @@ -2992,7 +2915,6 @@ paths: Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Mobile Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.210 ipLocation: @@ -3031,7 +2953,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.180 ipLocation: @@ -3070,7 +2991,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.180 ipLocation: @@ -3109,7 +3029,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.75 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.195 ipLocation: @@ -3148,7 +3067,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.75 Safari/537.36 - botProbability: 0 incognito: false ip: 45.86.200.179 ipLocation: @@ -3187,7 +3105,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.60 Safari/537.36 - botProbability: 0 incognito: false ip: 109.245.35.200 ipLocation: @@ -3231,7 +3148,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.60 Safari/537.36 - botProbability: 0 incognito: false ip: 109.245.35.200 ipLocation: @@ -3275,7 +3191,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36 - botProbability: 0 incognito: false ip: 178.223.21.183 ipLocation: @@ -3319,7 +3234,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36 - botProbability: 0 incognito: false ip: 87.116.165.97 ipLocation: @@ -3363,7 +3277,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36 - botProbability: 0 incognito: false ip: 87.116.165.97 ipLocation: @@ -3407,7 +3320,6 @@ paths: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36 - botProbability: 0 incognito: false ip: 87.116.165.97 ipLocation: @@ -3439,19 +3351,36 @@ paths: lastSeenAt: global: '2022-03-08T12:33:05.677Z' subscription: '2022-03-08T12:33:05.677Z' + '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' + examples: + 400-bad-request: + summary: >- + Error response when the visitor ID or query parameters are + missing or in the wrong format. + value: + error: bad request '403': - description: Forbidden. The API Key is probably missing or incorrect. + description: Forbidden. Access to this API is denied. content: application/json: schema: - $ref: '#/components/schemas/ErrorVisits403' + $ref: '#/components/schemas/ErrorPlainResponse' examples: - example: - summary: Forbidden + 403-forbidden: + summary: >- + Error response when the secret API Key is missing or + incorrect. value: error: Forbidden (HTTP 403) '429': - description: Too Many Requests + description: Too Many Requests. The request is throttled. headers: Retry-After: description: >- @@ -3464,10 +3393,12 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/TooManyRequestsResponse' + $ref: '#/components/schemas/ErrorPlainResponse' examples: - example: - summary: Too Many Requests + 429-too-many-requests: + summary: >- + Error response when the limit on the provided secret API key + requests per second has been exceeded. value: error: too many requests delete: @@ -3534,13 +3465,13 @@ paths: parameters: - name: visitor_id in: path - description: >- - The [visitor - ID](https://dev.fingerprint.com/docs/js-agent#visitorid) you want to - delete. required: true schema: type: string + description: >- + The [visitor + ID](https://dev.fingerprint.com/reference/get-function#visitorid) + you want to delete. responses: '200': description: OK. The visitor ID is scheduled for deletion. @@ -3551,18 +3482,18 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorVisitor400Response' + $ref: '#/components/schemas/ErrorResponse' examples: - 400-empty-visitor-id: + 400-visitor-id-required: summary: >- Error response when the request does not include a visitor - ID + ID. value: error: code: RequestCannotBeParsed message: visitor id is required - 400-invalid-visitor-id: - summary: Error response when the visitor ID is incorrectly formatted + 400-visitor-id-invalid: + summary: Error response when the visitor ID is incorrectly formatted. value: error: code: RequestCannotBeParsed @@ -3572,16 +3503,14 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon403Response' + $ref: '#/components/schemas/ErrorResponse' examples: - 403-feature-not-enabled: - summary: >- - Error response when this feature is not enabled for a - subscription. + 403-token-required: + summary: Error response when the secret API key was not provided. value: error: - code: FeatureNotEnabled - message: feature not enabled + code: TokenRequired + message: secret key is required 403-token-not-found: summary: >- Error response when the provided secret API key does not @@ -3590,12 +3519,6 @@ paths: error: code: TokenNotFound message: secret key is not found - 403-token-required: - summary: Error response when the secret API key was not provided. - value: - error: - code: TokenRequired - message: secret key is required 403-wrong-region: summary: >- Error response when the API region is different from the @@ -3604,6 +3527,20 @@ paths: error: code: WrongRegion message: wrong region + 403-subscription-not-active: + summary: Error response when the subscription is not active. + value: + error: + code: FeatureNotEnabled + message: feature not enabled + 403-feature-not-enabled: + summary: >- + Error response when this feature is not enabled for a + subscription. + value: + error: + code: SubscriptionNotActive + message: forbidden '404': description: >- Not found. The visitor ID cannot be found in this application's @@ -3611,10 +3548,12 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorVisitor404Response' + $ref: '#/components/schemas/ErrorResponse' examples: - example: - summary: Not found + 404-visitor-not-found: + summary: >- + Error response when the visitor ID cannot be found in this + application's data. value: error: code: VisitorNotFound @@ -3624,10 +3563,12 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon429Response' + $ref: '#/components/schemas/ErrorResponse' examples: - example: - summary: Too Many Requests + 429-too-many-requests: + summary: >- + Error response when the limit on the provided secret API key + requests per second has been exceeded. value: error: code: TooManyRequests @@ -3640,6 +3581,11 @@ paths: Fake path to describe webhook format. More information about webhooks can be found in the [documentation](https://dev.fingerprint.com/docs/webhooks) + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Webhook' responses: default: description: Dummy for the schema @@ -3655,22 +3601,17 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/WebhookVisit' + $ref: '#/components/schemas/Webhook' example: value: requestId: Px6VxbRC6WBkA39yeNH3 + url: https://banking.example.com/signup + ip: 216.3.128.12 tag: requestType: signup yourCustomId: 45321 - linkedId: any-string - visitorId: 3HNey93AkBW6CRbxV6xP - visitorFound: true - timestamp: 1554910997788 time: '2019-10-12T07:20:50.52Z' - incognito: false - url: https://banking.example.com/signup - clientReferrer: https://google.com?search=banking+services - ip: 216.3.128.12 + timestamp: 1554910997788 ipLocation: accuracyRadius: 1 city: @@ -3688,6 +3629,17 @@ paths: - isoCode: IL name: Illinois timezone: America/Chicago + linkedId: any-string + visitorId: 3HNey93AkBW6CRbxV6xP + visitorFound: true + confidence: + score: 0.97 + firstSeenAt: + global: '2022-03-16T11:26:45.362Z' + subscription: '2022-03-16T11:31:01.101Z' + lastSeenAt: + global: '2022-03-16T11:28:34.023Z' + subscription: null browserDetails: browserName: Chrome browserFullVersion: 73.0.3683.86 @@ -3698,20 +3650,18 @@ paths: userAgent: >- (Macintosh; Intel Mac OS X 10_14_3) Chrome/73.0.3683.86 - confidence: - score: 0.97 - firstSeenAt: - global: '2022-03-16T11:26:45.362Z' - subscription: '2022-03-16T11:31:01.101Z' - lastSeenAt: - global: '2022-03-16T11:28:34.023Z' - subscription: null + incognito: false + clientReferrer: https://google.com?search=banking+services bot: result: bad type: selenium userAgent: >- (Macintosh; Intel Mac OS X 10_14_3) Chrome/73.0.3683.86 + rootApps: + result: false + emulator: + result: false ipInfo: v4: address: 94.142.239.124 @@ -3739,10 +3689,6 @@ paths: datacenter: result: true name: DediPath - rootApps: - result: false - emulator: - result: false ipBlocklist: result: false details: @@ -3752,6 +3698,7 @@ paths: result: false vpn: result: false + confidence: high originTimezone: Europe/Berlin originCountry: unknown methods: @@ -3759,7 +3706,6 @@ paths: publicVPN: false auxiliaryMobile: false osMismatch: false - confidence: high proxy: result: false tampering: @@ -3868,15 +3814,15 @@ paths: reference](https://dev.fingerprint.com/reference/related-visitors-api). parameters: - name: visitor_id - description: >- - The [visitor - ID](https://dev.fingerprint.com/docs/js-agent#visitorid) for which - you want to find the other visitor IDs that originated from the same - mobile device. in: query required: true schema: type: string + description: >- + The [visitor + ID](https://dev.fingerprint.com/reference/get-function#visitorid) + for which you want to find the other visitor IDs that originated + from the same mobile device. responses: '200': description: OK. @@ -3902,18 +3848,18 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorVisitor400Response' + $ref: '#/components/schemas/ErrorResponse' examples: - 400-empty-visitor-id: + 400-visitor-id-required: summary: >- Error response when the request does not include a visitor - ID + ID. value: error: code: RequestCannotBeParsed message: visitor id is required - 400-invalid-visitor-id: - summary: Error response when the visitor ID is incorrectly formatted + 400-visitor-id-invalid: + summary: Error response when the visitor ID is incorrectly formatted. value: error: code: RequestCannotBeParsed @@ -3923,16 +3869,14 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon403Response' + $ref: '#/components/schemas/ErrorResponse' examples: - 403-feature-not-enabled: - summary: >- - Error response when this feature is not enabled for a - subscription. + 403-token-required: + summary: Error response when the secret API key was not provided. value: error: - code: FeatureNotEnabled - message: feature not enabled + code: TokenRequired + message: secret key is required 403-token-not-found: summary: >- Error response when the provided secret API key does not @@ -3941,12 +3885,6 @@ paths: error: code: TokenNotFound message: secret key is not found - 403-token-required: - summary: Error response when the secret API key was not provided. - value: - error: - code: TokenRequired - message: secret key is required 403-wrong-region: summary: >- Error response when the API region is different from the @@ -3955,6 +3893,20 @@ paths: error: code: WrongRegion message: wrong region + 403-subscription-not-active: + summary: Error response when the subscription is not active. + value: + error: + code: FeatureNotEnabled + message: feature not enabled + 403-feature-not-enabled: + summary: >- + Error response when this feature is not enabled for a + subscription. + value: + error: + code: SubscriptionNotActive + message: forbidden '404': description: >- Not found. The visitor ID cannot be found in this application's @@ -3962,7 +3914,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorVisitor404Response' + $ref: '#/components/schemas/ErrorResponse' examples: 404-visitor-not-found: summary: >- @@ -3977,10 +3929,12 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorCommon429Response' + $ref: '#/components/schemas/ErrorResponse' examples: - example: - summary: Too Many Requests + 429-too-many-requests: + summary: >- + Error response when the limit on the provided secret API key + requests per second has been exceeded. value: error: code: TooManyRequests @@ -3999,117 +3953,218 @@ components: BrowserDetails: type: object additionalProperties: false + required: + - browserName + - browserFullVersion + - browserMajorVersion + - os + - osVersion + - device + - userAgent properties: browserName: type: string - example: Chrome browserMajorVersion: type: string - example: '101' browserFullVersion: type: string - example: 101.0.4951 os: type: string - example: Windows osVersion: type: string - example: '10' device: type: string - example: Other userAgent: type: string - example: >- - Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, - like Gecko) Chrome/101.0.4951.41 Safari/537.36 - botProbability: - type: integer + GeolocationCity: + type: object + additionalProperties: false required: - - browserFullVersion - - browserMajorVersion - - browserName - - device - - os - - osVersion - - userAgent - title: BrowserDetails - Location: + - name + properties: + name: + type: string + GeolocationCountry: type: object additionalProperties: false + required: + - code + - name properties: code: type: string minLength: 2 maxLength: 2 - example: US name: type: string - example: United States + GeolocationContinent: + type: object + additionalProperties: false required: - code - name - title: Location - Subdivision: + properties: + code: + type: string + minLength: 2 + maxLength: 2 + name: + type: string + GeolocationSubdivision: type: object additionalProperties: false + required: + - isoCode + - name properties: isoCode: type: string - example: '10' name: type: string - example: Hlavni mesto Praha - Confidence: + 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://dev.fingerprint.com/docs/smart-signals-overview#ip-geolocation) + for geolocation information. additionalProperties: false properties: - score: + accuracyRadius: + type: integer + minimum: 0 description: >- - The confidence score is a floating-point number between 0 and 1 that - represents the probability of accurate identification. + 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: float + 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 - required: - - score - title: Confidence - SeenAt: + IdentificationSeenAt: type: object additionalProperties: false + required: + - global + - subscription properties: global: type: string nullable: true format: date-time - example: '2022-05-05T18:28:54.535Z' subscription: type: string nullable: true format: date-time - example: '2022-06-09T22:58:05.576Z' - required: - - global - - subscription - title: SeenAt - example: - global: '2022-05-05T18:28:54.535Z' - subscription: null - Visit: + 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' + Identification: type: object additionalProperties: false + required: + - visitorId + - requestId + - browserDetails + - incognito + - ip + - timestamp + - time + - url + - tag + - visitorFound + - firstSeenAt + - lastSeenAt properties: + visitorId: + type: string + description: >- + String of 20 characters that uniquely identifies the visitor's + browser. requestId: - description: Unique identifier of the user's identification request. type: string - example: 1654815516083.OX6kx8 + description: Unique identifier of the user's request. browserDetails: $ref: '#/components/schemas/BrowserDetails' incognito: @@ -4118,283 +4173,293 @@ components: ip: type: string format: ipv4 - example: 8.8.8.8 + description: IP address of the requesting browser or bot. ipLocation: - type: object - additionalProperties: false - deprecated: true - 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. - properties: - accuracyRadius: - description: >- - The IP address is likely to be within this radius (in km) of the - specified location. - type: integer - minimum: 0 - 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: - type: object - additionalProperties: false - title: DeprecatedIPLocationCity - properties: - name: - type: string - country: - $ref: '#/components/schemas/Location' - continent: - $ref: '#/components/schemas/Location' - subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: DeprecatedIPLocation + $ref: '#/components/schemas/DeprecatedGeolocation' + linkedId: + type: string + description: A customer-provided id that was sent with the request. timestamp: description: Timestamp of the event with millisecond precision in Unix time. type: integer format: int64 - example: 1654815516086 time: - title: Time - description: Time expressed according to ISO 8601 in UTC format. type: string format: date-time - example: '2022-06-09T22:58:36Z' + 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: - description: Page URL from which the identification request was sent. type: string - example: https://some.website/path?query=params + description: Page URL from which the request was sent. tag: - description: >- - A customer-provided value or an object that was sent with - identification request. - type: object - additionalProperties: true - linkedId: - description: A customer-provided id that was sent with identification request. - type: string - example: someID + $ref: '#/components/schemas/Tag' confidence: - $ref: '#/components/schemas/Confidence' + $ref: '#/components/schemas/IdentificationConfidence' visitorFound: - description: Attribute represents if a visitor had been identified before. type: boolean + description: Attribute represents if a visitor had been identified before. firstSeenAt: - $ref: '#/components/schemas/SeenAt' + $ref: '#/components/schemas/IdentificationSeenAt' lastSeenAt: - $ref: '#/components/schemas/SeenAt' - required: - - browserDetails - - firstSeenAt - - incognito - - ip - - lastSeenAt - - requestId - - time - - timestamp - - url - - visitorFound - title: Visit - IdentificationError: + $ref: '#/components/schemas/IdentificationSeenAt' + components: + $ref: '#/components/schemas/RawDeviceAttributes' + ErrorCode: + type: string + enum: + - RequestCannotBeParsed + - TokenRequired + - TokenNotFound + - SubscriptionNotActive + - WrongRegion + - FeatureNotEnabled + - 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. + * `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: - type: string - description: | - Error code: - * `429 Too Many Requests` - the limit on secret API key requests per second has been exceeded - * `Failed` - internal server error - enum: - - 429 Too Many Requests - - Failed - example: 429 Too Many Requests + $ref: '#/components/schemas/ErrorCode' message: type: string - example: too many requests - required: - - code - - message - BotdDetectionResult: + 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: - type: string - 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 - enum: - - notDetected - - good - - bad - example: bad + $ref: '#/components/schemas/BotdBotResult' type: type: string - example: selenium - required: - - result - BotdResult: + Botd: type: object - additionalProperties: false 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 format: ipv4 - example: 8.8.8.8 description: IP address of the requesting browser or bot. time: - title: Time + type: string + format: date-time 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 + malicious. Otherwise, request replay attacks are possible. + userAgent: type: string - format: date-time - example: '2022-06-09T22:58:36Z' - url: - description: Page URL from which identification request was sent. - type: string - example: https://example.com/login - userAgent: - type: string - example: >- - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 - (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 requestId: type: string - example: 1681392853693.lRiBBD - linkedId: - type: string - example: Automatic tests bot - bot: - $ref: '#/components/schemas/BotdDetectionResult' + 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: - - bot - - url - - ip - - time - - userAgent - - requestId - ProductError: + - 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: - code: - type: string - description: | - Error code: - * `TooManyRequests` - the limit on secret API key requests per second has been exceeded - * `Failed` - internal server error - enum: - - TooManyRequests - - Failed - example: TooManyRequests - message: - type: string - example: too many requests + data: + $ref: '#/components/schemas/RootApps' + error: + $ref: '#/components/schemas/Error' + Emulator: + type: object + additionalProperties: false required: - - code - - message - IPLocation: + - 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. - type: integer - minimum: 0 - example: 1000 latitude: type: number format: double minimum: -90 maximum: 90 - example: 37.75 longitude: type: number format: double minimum: -180 maximum: 180 - example: -97.82 postalCode: type: string - example: 130 00 timezone: type: string format: timezone - example: America/Chicago city: - type: object - additionalProperties: false - title: IPLocationCity - properties: - name: - type: string - example: Prague + $ref: '#/components/schemas/GeolocationCity' country: - $ref: '#/components/schemas/Location' + $ref: '#/components/schemas/GeolocationCountry' continent: - $ref: '#/components/schemas/Location' + $ref: '#/components/schemas/GeolocationContinent' subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: IPLocation - ASN: + $ref: '#/components/schemas/GeolocationSubdivisions' + IPInfoASN: type: object additionalProperties: false + required: + - asn + - name + - network properties: asn: type: string - example: '7922' - network: - type: string - example: 73.136.0.0/13 name: type: string - example: COMCAST-7922 - required: - - asn - - network - title: ASN - DataCenter: + network: + type: string + IPInfoDataCenter: type: object additionalProperties: false + required: + - result + - name properties: result: type: boolean name: type: string - example: DediPath + 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: - - result - title: DataCenter - IpInfoResult: + - 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 @@ -4402,432 +4467,465 @@ components: additionalProperties: false properties: v4: - type: object - additionalProperties: false - properties: - address: - type: string - format: ipv4 - example: 94.142.239.124 - geolocation: - $ref: '#/components/schemas/IPLocation' - asn: - $ref: '#/components/schemas/ASN' - datacenter: - $ref: '#/components/schemas/DataCenter' - required: - - address - - geolocation + $ref: '#/components/schemas/IPInfoV4' v6: - type: object - additionalProperties: false - properties: - address: - type: string - format: ipv6 - example: 2001:0db8:85a3:0000:0000:8a2e:0370:7334 - geolocation: - $ref: '#/components/schemas/IPLocation' - asn: - $ref: '#/components/schemas/ASN' - datacenter: - $ref: '#/components/schemas/DataCenter' - required: - - address - - geolocation - IncognitoResult: + $ref: '#/components/schemas/IPInfoV6' + ProductIPInfo: type: object additionalProperties: false properties: - result: - type: boolean - description: > - `true` if we detected incognito mode used in the browser, `false` - otherwise. - example: false - required: - - result - RootAppsResult: + data: + $ref: '#/components/schemas/IPInfo' + error: + $ref: '#/components/schemas/Error' + IPBlocklistDetails: 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. - example: false required: - - result - EmulatorResult: - type: object - additionalProperties: false + - emailSpam + - attackSource properties: - result: + emailSpam: 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. - example: false - required: - - result - ClonedAppResult: - type: object - additionalProperties: false - properties: - result: + description: IP address was part of a known email spam attack (SMTP). + attackSource: 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. - example: false - required: - - result - FactoryResetResult: + description: IP address was part of a known network attack (SSH/HTTPS). + IPBlocklist: type: object additionalProperties: false - properties: - 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. - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - timestamp: - 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. - type: integer - format: int64 - example: 1654815517198 required: - - time - - timestamp - JailbrokenResult: - type: object - additionalProperties: false + - result + - details 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. - example: false - required: - - result - FridaResult: + `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: - 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. - example: false - required: - - result - IpBlockListResult: + data: + $ref: '#/components/schemas/IPBlocklist' + error: + $ref: '#/components/schemas/Error' + Tor: 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. - example: false - details: - type: object - additionalProperties: false - properties: - emailSpam: - type: boolean - description: IP address was part of a known email spam attack (SMTP). - example: false - attackSource: - type: boolean - description: IP address was part of a known network attack (SSH/HTTPS). - example: false - required: - - emailSpam - - attackSource required: - result - - details - TorResult: - type: object - additionalProperties: false properties: result: type: boolean description: > `true` if the request IP address is a known tor exit node, `false` otherwise. - example: false - required: - - result - PrivacySettingsResult: + ProductTor: 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`. - example: false - required: - - result - VirtualMachineResult: + 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 properties: - result: + timezoneMismatch: type: boolean - description: > - `true` if the request came from a browser running inside a virtual - machine (e.g. VMWare), `false` otherwise. - example: false - required: - - result - VpnResult: + 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. + 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. - example: false + confidence: + $ref: '#/components/schemas/VPNConfidence' originTimezone: type: string description: Local timezone which is used in timezoneMismatch method. - example: Europe/Berlin originCountry: type: string description: >- Country of the request (only for Android SDK version >= 2.4.0, ISO 3166 format or unknown). - example: unknown methods: - type: object - additionalProperties: false - properties: - timezoneMismatch: - type: boolean - description: >- - The browser timezone doesn't match the timezone inferred from - the request IP address. - example: false - publicVPN: - type: boolean - description: >- - Request IP address is owned and used by a public VPN service - provider. - example: false - 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. - example: false - osMismatch: - type: boolean - description: >- - The browser runs on a different operating system than the - operating system inferred from the request network signature. - example: false - required: - - timezoneMismatch - - publicVPN - - auxiliaryMobile - - osMismatch - confidence: - 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. - example: low - required: - - result - - originTimezone - - methods - - confidence - ProxyResult: + $ref: '#/components/schemas/VPNMethods' + ProductVPN: + type: object + additionalProperties: false + properties: + data: + $ref: '#/components/schemas/VPN' + error: + $ref: '#/components/schemas/Error' + Proxy: type: object additionalProperties: false + required: + - result properties: result: type: boolean description: > `true` if the request IP address is used by a public proxy provider, `false` otherwise. - example: false + ProductProxy: + type: object + additionalProperties: false + properties: + data: + $ref: '#/components/schemas/Proxy' + error: + $ref: '#/components/schemas/Error' + Incognito: + type: object + additionalProperties: false required: - result - TamperingResult: + 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 + - anomalyScore + - antiDetectBrowser properties: result: type: boolean - description: >- + description: > Flag indicating browser tampering was detected. This happens when either of these conditions is true: * There are inconsistencies in the browser configuration that cross our internal tampering thresholds (indicated by `anomalyScore`). * The browser signature resembles one of "anti-detect" browsers specifically designed to evade identification and fingerprinting, for example, Incognition (indicated by `antiDetectBrowser`). - example: false anomalyScore: type: number - description: >- - Confidence score (`0.0 - 1.0`) for tampering detection. Values above - `0.5` indicate that there was a tampering attempt. Values below - `0.5` indicate genuine browsers. - example: 0 + format: double minimum: 0 maximum: 1 + description: | + Confidence score (`0.0 - 1.0`) for tampering detection: + * Values above `0.5` indicate that there was a tampering attempt. + * Values below `0.5` indicate genuine browsers. antiDetectBrowser: type: boolean description: >- Is `true` if the identified browser resembles one of "anti-detect" - browsers, for example, Incognition. Anti-detect browsers try to + browsers, for example, Incognition. Anti-detect browsers try to evade identification by masking or manipulating their fingerprint to imitate legitimate browser configurations. - example: false - required: - - result - - anomalyScore - - antiDetectBrowser - HighActivityResult: + ProductTampering: type: object additionalProperties: false properties: - result: - type: boolean - description: >- - Flag indicating whether the request came from a high activity - visitor. - example: false - dailyRequests: - type: number - description: Number of requests from the same visitor in the previous day. - example: 10 - minimum: 1 - required: - - result - LocationSpoofingResult: + data: + $ref: '#/components/schemas/Tampering' + error: + $ref: '#/components/schemas/Error' + ClonedApp: 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. - example: false - required: - - result - SuspectScoreResult: + 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: - 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 + 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://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. + 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. + 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' + 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. + 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://dev.fingerprint.com/docs/suspect-score - example: 0 - required: - - result - RawDeviceAttributesResult: + ProductSuspectScore: 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: - type: object - properties: - error: - properties: - name: - title: error.name - type: string - message: - title: error.message - type: string - required: - - name - - message - title: error - type: object - value: - title: value - RemoteControlResult: + additionalProperties: false + properties: + data: + $ref: '#/components/schemas/SuspectScore' + error: + $ref: '#/components/schemas/Error' + RemoteControl: type: object 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. - example: false - required: - - result - VelocityIntervalResult: + ProductRemoteControl: + type: object + 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 - example: 1 1h: type: integer - example: 1 24h: type: integer description: > @@ -4836,17 +4934,13 @@ components: `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. - example: 1 - required: - - 5m - - 1h - VelocityIntervals: + VelocityData: type: object additionalProperties: false properties: intervals: - $ref: '#/components/schemas/VelocityIntervalResult' - VelocityResult: + $ref: '#/components/schemas/VelocityIntervals' + Velocity: type: object description: > Sums key data points for a specific `visitorId`, `ipAddress` and @@ -4855,15 +4949,16 @@ components: intervals: 5 minutes, 1 hour, and 24 hours as follows: - - Number of identification events associated with the visitor ID. + - Number of distinct IP addresses associated to the visitor ID. - Number of distinct linked IDs associated with the visitor ID. - - Number of distinct IP addresses associated to the visitor ID. - - Number of distinct countries associated with the visitor ID. - - Number of events associated for the detected IP address. + - 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. @@ -4881,42 +4976,57 @@ components: hours (`events.intervals.['24h']`) is higher than 20.000. additionalProperties: false - properties: - events: - $ref: '#/components/schemas/VelocityIntervals' - distinctLinkedId: - $ref: '#/components/schemas/VelocityIntervals' - distinctIp: - $ref: '#/components/schemas/VelocityIntervals' - distinctCountry: - $ref: '#/components/schemas/VelocityIntervals' - ipEvents: - $ref: '#/components/schemas/VelocityIntervals' - distinctIpByLinkedId: - $ref: '#/components/schemas/VelocityIntervals' - distinctVisitorIdByLinkedId: - $ref: '#/components/schemas/VelocityIntervals' required: - - events - - distinctLinkedId - distinctIp + - distinctLinkedId - distinctCountry + - events - ipEvents - distinctIpByLinkedId - distinctVisitorIdByLinkedId - DeveloperToolsResult: + 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 is Chrome with DevTools open or Firefox with Developer Tools open, `false` otherwise. - example: false - required: - - result - ProductsResponse: + ProductDeveloperTools: + type: object + additionalProperties: false + properties: + data: + $ref: '#/components/schemas/DeveloperTools' + error: + $ref: '#/components/schemas/Error' + Products: type: object description: >- Contains all information about the request identified by `requestId`, @@ -4924,897 +5034,614 @@ components: additionalProperties: false properties: identification: - type: object - additionalProperties: false - title: ProductsResponseIdentification - properties: - data: - title: ProductsResponseIdentificationData - type: object - properties: - requestId: - description: Unique identifier of the user's identification request. - type: string - example: 1654815516083.OX6kx8 - browserDetails: - $ref: '#/components/schemas/BrowserDetails' - incognito: - description: Flag if user used incognito session. - type: boolean - ip: - type: string - format: ipv4 - example: 8.8.8.8 - ipLocation: - type: object - additionalProperties: false - deprecated: true - 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. - properties: - accuracyRadius: - description: >- - The IP address is likely to be within this radius (in - km) of the specified location. - type: integer - minimum: 0 - 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: - type: object - additionalProperties: false - title: DeprecatedIPLocationCity - properties: - name: - type: string - country: - $ref: '#/components/schemas/Location' - continent: - $ref: '#/components/schemas/Location' - subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: DeprecatedIPLocation - timestamp: - description: >- - Timestamp of the event with millisecond precision in Unix - time. - type: integer - format: int64 - example: 1654815516086 - time: - title: Time - description: Time expressed according to ISO 8601 in UTC format. - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - url: - description: Page URL from which the identification request was sent. - type: string - example: https://some.website/path?query=params - tag: - description: >- - A customer-provided value or an object that was sent with - identification request. - type: object - additionalProperties: true - linkedId: - description: >- - A customer-provided id that was sent with identification - request. - type: string - example: someID - confidence: - $ref: '#/components/schemas/Confidence' - visitorFound: - description: >- - Attribute represents if a visitor had been identified - before. - type: boolean - firstSeenAt: - $ref: '#/components/schemas/SeenAt' - lastSeenAt: - $ref: '#/components/schemas/SeenAt' - visitorId: - type: string - description: > - String of 20 characters that uniquely identifies the - visitor's browser. - example: - - Ibk1527CUFmcnjLwIs4A - additionalProperties: false - required: - - browserDetails - - firstSeenAt - - incognito - - ip - - lastSeenAt - - requestId - - time - - timestamp - - url - - visitorFound - - visitorId - - tag - error: - $ref: '#/components/schemas/IdentificationError' + $ref: '#/components/schemas/ProductIdentification' botd: - title: ProductsResponseBotd - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/BotdResult' - error: - $ref: '#/components/schemas/ProductError' - ipInfo: - title: SignalResponseIpInfo - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/IpInfoResult' - error: - $ref: '#/components/schemas/ProductError' - incognito: - title: SignalResponseIncognito - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/IncognitoResult' - error: - $ref: '#/components/schemas/IdentificationError' + $ref: '#/components/schemas/ProductBotd' rootApps: - title: SignalResponseRootApps - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/RootAppsResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductRootApps' emulator: - title: SignalResponseEmulator - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/EmulatorResult' - error: - $ref: '#/components/schemas/ProductError' + $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: - title: SignalResponseClonedApp - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/ClonedAppResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductClonedApp' factoryReset: - title: SignalResponseFactoryReset - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/FactoryResetResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductFactoryReset' jailbroken: - title: SignalResponseJailbroken - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/JailbrokenResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductJailbroken' frida: - title: SignalResponseFrida - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/FridaResult' - error: - $ref: '#/components/schemas/ProductError' - ipBlocklist: - title: SignalResponseIpBlocklist - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/IpBlockListResult' - error: - $ref: '#/components/schemas/ProductError' - tor: - title: SignalResponseTor - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/TorResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductFrida' privacySettings: - title: SignalResponsePrivacySettings - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/PrivacySettingsResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductPrivacySettings' virtualMachine: - title: SignalResponseVirtualMachine - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/VirtualMachineResult' - error: - $ref: '#/components/schemas/ProductError' - vpn: - title: SignalResponseVpn - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/VpnResult' - error: - $ref: '#/components/schemas/ProductError' - proxy: - title: SignalResponseProxy - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/ProxyResult' - error: - $ref: '#/components/schemas/ProductError' - tampering: - title: SignalResponseTampering - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/TamperingResult' - error: - $ref: '#/components/schemas/IdentificationError' + $ref: '#/components/schemas/ProductVirtualMachine' + rawDeviceAttributes: + $ref: '#/components/schemas/ProductRawDeviceAttributes' highActivity: - title: SignalResponseHighActivity - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/HighActivityResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductHighActivity' locationSpoofing: - title: SignalResponseLocationSpoofing - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/LocationSpoofingResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductLocationSpoofing' suspectScore: - title: SignalResponseSuspectScore - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/SuspectScoreResult' - error: - $ref: '#/components/schemas/ProductError' - rawDeviceAttributes: - title: SignalResponseRawDeviceAttributes - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/RawDeviceAttributesResult' - error: - $ref: '#/components/schemas/IdentificationError' + $ref: '#/components/schemas/ProductSuspectScore' remoteControl: - title: SignalResponseRemoteControl - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/RemoteControlResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductRemoteControl' velocity: - title: SignalResponseVelocity - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/VelocityResult' - error: - $ref: '#/components/schemas/ProductError' + $ref: '#/components/schemas/ProductVelocity' developerTools: - title: SignalResponseDeveloperTools - type: object - additionalProperties: false - properties: - data: - $ref: '#/components/schemas/DeveloperToolsResult' - error: - $ref: '#/components/schemas/ProductError' - EventResponse: + $ref: '#/components/schemas/ProductDeveloperTools' + EventsGetResponse: + type: object description: >- Contains results from all activated products - Fingerprint Pro, Bot Detection, and others. - type: object additionalProperties: false - properties: - products: - $ref: '#/components/schemas/ProductsResponse' - error: - $ref: '#/components/schemas/ProductError' required: - products - ErrorCommon403Response: - type: object - additionalProperties: false properties: - error: - type: object - additionalProperties: false - title: Common403ErrorResponse - properties: - code: - type: string - description: | - Error code: - * `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 - enum: - - TokenRequired - - TokenNotFound - - SubscriptionNotActive - - WrongRegion - - FeatureNotEnabled - example: TokenRequired - message: - type: string - example: secret key is required - required: - - code - - message - ErrorEvent404Response: + products: + $ref: '#/components/schemas/Products' + ErrorResponse: type: object additionalProperties: false + required: + - error properties: error: - type: object - additionalProperties: false - title: ErrorEvent404ResponseError - properties: - code: - type: string - description: | - Error code: - * `RequestNotFound` - The specified request ID was not found. It never existed, expired, or it has been deleted. - enum: - - RequestNotFound - example: RequestNotFound - message: - type: string - example: request id is not found - required: - - code - - message - EventUpdateRequest: + $ref: '#/components/schemas/Error' + EventsUpdateRequest: type: object properties: linkedId: type: string description: LinkedID value to assign to the existing event tag: - type: object - description: >- - Full `tag` value to be set to the existing event. Replaces any - existing `tag` payload completely. + $ref: '#/components/schemas/Tag' suspect: type: boolean description: Suspect flag indicating observed suspicious or fraudulent event - ErrorUpdateEvent400Response: - type: object - additionalProperties: false - properties: - error: - type: object - additionalProperties: false - title: ErrorUpdateEvent400ResponseError - properties: - code: - type: string - description: > - Error code: * `RequestCannotBeParsed` - the JSON content of the - request contains some errors that prevented us from parsing it - (wrong type/surpassed limits) * `Failed` - the event is more - than 10 days old and cannot be updated - enum: - - RequestCannotBeParsed - - Failed - example: RequestCannotBeParsed - message: - type: string - description: Details about the underlying issue with the input payload - example: suspect flag must be a boolean - required: - - code - - message - ErrorUpdateEvent409Response: + Visit: type: object additionalProperties: false + required: + - requestId + - browserDetails + - incognito + - ip + - timestamp + - time + - url + - tag + - visitorFound + - firstSeenAt + - lastSeenAt properties: - error: - type: object - additionalProperties: false - title: ErrorUpdateEvent409ResponseError - properties: - code: - type: string - description: > - Error code: * `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. - enum: - - StateNotReady - example: StateNotReady - message: - type: string - example: resource is not mutable yet, try again - required: - - code - - message - Response: + 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 + format: ipv4 + 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 + 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: >- + Pagination-related fields `lastTimestamp` and `paginationKey` are + included if you use a pagination parameter like `limit` or `before` and + there is more data available on the next page. additionalProperties: false + required: + - visitorId + - visits properties: visitorId: type: string visits: type: array items: - title: ResponseVisits - type: object - properties: - requestId: - description: Unique identifier of the user's identification request. - type: string - example: 1654815516083.OX6kx8 - browserDetails: - $ref: '#/components/schemas/BrowserDetails' - incognito: - description: Flag if user used incognito session. - type: boolean - ip: - type: string - format: ipv4 - example: 8.8.8.8 - ipLocation: - type: object - additionalProperties: false - deprecated: true - 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. - properties: - accuracyRadius: - description: >- - The IP address is likely to be within this radius (in km) - of the specified location. - type: integer - minimum: 0 - 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: - type: object - additionalProperties: false - title: DeprecatedIPLocationCity - properties: - name: - type: string - country: - $ref: '#/components/schemas/Location' - continent: - $ref: '#/components/schemas/Location' - subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: DeprecatedIPLocation - timestamp: - description: >- - Timestamp of the event with millisecond precision in Unix - time. - type: integer - format: int64 - example: 1654815516086 - time: - title: Time - description: Time expressed according to ISO 8601 in UTC format. - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - url: - description: Page URL from which the identification request was sent. - type: string - example: https://some.website/path?query=params - tag: - description: >- - A customer-provided value or an object that was sent with - identification request. - type: object - additionalProperties: true - linkedId: - description: >- - A customer-provided id that was sent with identification - request. - type: string - example: someID - confidence: - $ref: '#/components/schemas/Confidence' - visitorFound: - description: Attribute represents if a visitor had been identified before. - type: boolean - firstSeenAt: - $ref: '#/components/schemas/SeenAt' - lastSeenAt: - $ref: '#/components/schemas/SeenAt' - additionalProperties: false - required: - - browserDetails - - firstSeenAt - - incognito - - ip - - lastSeenAt - - requestId - - time - - timestamp - - url - - visitorFound - - tag + $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. - type: integer - format: int64 - example: 1654815517198 paginationKey: + type: string description: >- Request ID of the last visit in the current page of results. Use this value in the following request as the `paginationKey` parameter to get the next page of results. - type: string - example: 1654815517198.azN4IZ + ErrorPlainResponse: + type: object + additionalProperties: false required: - - visitorId - - visits - title: PaginatedResponse + - error + properties: + error: + type: string + 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: >- - Fields `lastTimestamp` and `paginationKey` added when `limit` or - `before` parameter provided and there is more data to show - ErrorVisits403: + 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: - error: + 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' + originTimezone: type: string - description: Error text. - example: Forbidden (HTTP 403) - required: - - error - TooManyRequestsResponse: + 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: - error: + result: + type: boolean + description: > + `true` if the request IP address is used by a public proxy provider, + `false` otherwise. + WebhookTampering: + type: object + additionalProperties: false + properties: + result: + type: boolean + description: > + Flag indicating browser tampering was detected. This happens when + either of these conditions is true: + * There are inconsistencies in the browser configuration that cross our internal tampering thresholds (indicated by `anomalyScore`). + * The browser signature resembles one of "anti-detect" browsers specifically designed to evade identification and fingerprinting, for example, Incognition (indicated by `antiDetectBrowser`). + anomalyScore: + type: number + format: double + minimum: 0 + maximum: 1 + description: | + Confidence score (`0.0 - 1.0`) for tampering detection: + * Values above `0.5` indicate that there was a tampering attempt + * Values below `0.5` indicate genuine browsers. + antiDetectBrowser: + type: boolean + description: >- + Is `true` if the identified browser resembles one of "anti-detect" + browsers, for example, Incognition. Anti-detect browsers try to + evade identification by masking or manipulating their fingerprint to + imitate legitimate browser configurations. + 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 - description: Error text. - example: request throttled + 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. + 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. + 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: - - error - ErrorVisitor400Response: + - 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: - error: - type: object - additionalProperties: false - properties: - code: - type: string - description: > - Error code: * `RequestCannotBeParsed` - The visitor ID parameter - is missing or in the wrong format. - enum: - - RequestCannotBeParsed - example: RequestCannotBeParsed - message: - type: string - example: invalid visitor id - required: - - code - - message - ErrorVisitor404Response: + result: + type: boolean + description: >- + Flag indicating whether the request came from a mobile device with + location spoofing enabled. + WebhookSuspectScore: type: object additionalProperties: false properties: - error: - type: object - additionalProperties: false - title: ErrorVisitor404ResponseError - properties: - code: - type: string - description: > - Error code: * `VisitorNotFound` - The specified visitor ID was - not found. It never existed or it may have already been deleted. - enum: - - VisitorNotFound - example: VisitorNotFound - message: - type: string - example: visitor not found - required: - - code - - message - ErrorCommon429Response: + 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 + WebhookRemoteControl: type: object additionalProperties: false properties: - error: - type: object - additionalProperties: false - properties: - code: - type: string - description: | - Error code: * `TooManyRequests` - The request is throttled. - enum: - - TooManyRequests - example: TooManyRequests - message: - type: string - example: request throttled - required: - - code - - message - WebhookVisit: + 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 is Chrome with DevTools open or Firefox with + Developer Tools open, `false` otherwise. + Webhook: + type: object + required: + - requestId + - url + - ip + - time + - timestamp + 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 + format: ipv4 + description: IP address of the requesting browser or bot. + tag: + $ref: '#/components/schemas/Tag' + time: + type: string + format: date-time + 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 - example: 3HNey93AkBW6CRbxV6xP + description: >- + String of 20 characters that uniquely identifies the visitor's + browser. + 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 - example: https://google.com?search=banking+services + components: + $ref: '#/components/schemas/RawDeviceAttributes' + bot: + $ref: '#/components/schemas/BotdBot' userAgent: type: string - example: >- - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 - (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 - bot: - $ref: '#/components/schemas/BotdDetectionResult' - ipInfo: - $ref: '#/components/schemas/IpInfoResult' - incognito: - description: Flag if user used incognito session. - type: boolean rootApps: - $ref: '#/components/schemas/RootAppsResult' + $ref: '#/components/schemas/WebhookRootApps' emulator: - $ref: '#/components/schemas/EmulatorResult' + $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/ClonedAppResult' + $ref: '#/components/schemas/WebhookClonedApp' factoryReset: - $ref: '#/components/schemas/FactoryResetResult' + $ref: '#/components/schemas/WebhookFactoryReset' jailbroken: - $ref: '#/components/schemas/JailbrokenResult' + $ref: '#/components/schemas/WebhookJailbroken' frida: - $ref: '#/components/schemas/FridaResult' - ipBlocklist: - $ref: '#/components/schemas/IpBlockListResult' - tor: - $ref: '#/components/schemas/TorResult' + $ref: '#/components/schemas/WebhookFrida' privacySettings: - $ref: '#/components/schemas/PrivacySettingsResult' + $ref: '#/components/schemas/WebhookPrivacySettings' virtualMachine: - $ref: '#/components/schemas/VirtualMachineResult' - vpn: - $ref: '#/components/schemas/VpnResult' - proxy: - $ref: '#/components/schemas/ProxyResult' - tampering: - $ref: '#/components/schemas/TamperingResult' + $ref: '#/components/schemas/WebhookVirtualMachine' rawDeviceAttributes: - $ref: '#/components/schemas/RawDeviceAttributesResult' + $ref: '#/components/schemas/WebhookRawDeviceAttributes' highActivity: - $ref: '#/components/schemas/HighActivityResult' + $ref: '#/components/schemas/WebhookHighActivity' locationSpoofing: - $ref: '#/components/schemas/LocationSpoofingResult' + $ref: '#/components/schemas/WebhookLocationSpoofing' suspectScore: - $ref: '#/components/schemas/SuspectScoreResult' + $ref: '#/components/schemas/WebhookSuspectScore' remoteControl: - $ref: '#/components/schemas/RemoteControlResult' + $ref: '#/components/schemas/WebhookRemoteControl' velocity: - $ref: '#/components/schemas/VelocityResult' + $ref: '#/components/schemas/WebhookVelocity' developerTools: - $ref: '#/components/schemas/DeveloperToolsResult' - requestId: - description: Unique identifier of the user's identification request. - type: string - example: 1654815516083.OX6kx8 - browserDetails: - $ref: '#/components/schemas/BrowserDetails' - ip: - type: string - format: ipv4 - example: 8.8.8.8 - ipLocation: - type: object - additionalProperties: false - deprecated: true - 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. - properties: - accuracyRadius: - description: >- - The IP address is likely to be within this radius (in km) of the - specified location. - type: integer - minimum: 0 - 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: - type: object - additionalProperties: false - title: DeprecatedIPLocationCity - properties: - name: - type: string - country: - $ref: '#/components/schemas/Location' - continent: - $ref: '#/components/schemas/Location' - subdivisions: - type: array - items: - $ref: '#/components/schemas/Subdivision' - title: DeprecatedIPLocation - timestamp: - description: Timestamp of the event with millisecond precision in Unix time. - type: integer - format: int64 - example: 1654815516086 - time: - title: Time - description: Time expressed according to ISO 8601 in UTC format. - type: string - format: date-time - example: '2022-06-09T22:58:36Z' - url: - description: Page URL from which the identification request was sent. - type: string - example: https://some.website/path?query=params - tag: - description: >- - A customer-provided value or an object that was sent with - identification request. - type: object - additionalProperties: true - linkedId: - description: A customer-provided id that was sent with identification request. - type: string - example: someID - confidence: - $ref: '#/components/schemas/Confidence' - visitorFound: - description: Attribute represents if a visitor had been identified before. - type: boolean - firstSeenAt: - $ref: '#/components/schemas/SeenAt' - lastSeenAt: - $ref: '#/components/schemas/SeenAt' - additionalProperties: false - required: - - visitorId - - browserDetails - - firstSeenAt - - incognito - - ip - - lastSeenAt - - requestId - - time - - timestamp - - url - - visitorFound + $ref: '#/components/schemas/WebhookDeveloperTools' 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. - type: string - example: Ibk1527CUFmcnjLwIs4A - required: - - visitorId RelatedVisitorsResponse: type: object additionalProperties: false + required: + - relatedVisitors properties: relatedVisitors: type: array items: $ref: '#/components/schemas/RelatedVisitor' - required: - - relatedVisitors