> >

API

API Request Domain

https://riskct.geetest.com

Authentication Method

The server query interface requires signature verification using the HMAC-SHA256 signing algorithm. The KEY used by HMAC is the PRIVATE_KEY defined by APP_ID, which needs to be created and obtained on the dashboard.

The message for signing consists of the APP_ID and timestamp.

sign_token = hmac(key=private_key, msg=app_id+gen_time, digestmod='SHA256').hexdigest()

Fingerprint Query API

POST /dfp/api/v1/fp_query

The “BODY” request parameter

Format: JSON

Parameter Name	Required	Type	Description
app_id	Yes	String	It is obtained by applying for an application on GeeTest’s dashboard
gen_time	Yes	integer	Timestamp used for signature, accurate to seconds
gee_token	Yes	String	Data collected by the client SDK, valid for 10 munites
scene	No	String	“The current query scene 1. login 2. sign_up 3. activity Default value is “activity”
sign_token	Yes	String	Data signature, see Authentication Method for signature method
attr	No	Object	Used for submitting account data

attr Parameter Explaination

Name	Required	Type	Description
user_ip	No	String	User IP address, supports both ipv4 and ipv6 formats
user_id	No	String	User’s account ID

Sample Parameters

{
    "app_id": "Your app_id",
    "sign_token": "signature result",
    "gen_time": 1657165827,
    "gee_toekn":"RzAwAGPc833Ng3+5Oi46UMZCFEyhx0BG3zHChnwAxEElDMVJmZqJ8w0o9EQgCa/OtTizACuwgu3KPP+gezqneTZH6IR2FG7ZuBZZZknrtm12SaQjRbtNrF3YMpShubxpmDsmNctckNdep0WFdbJ9NtoC/yyO8b5hgkiLVGa1j3Oc293tizSGmkBHw0Czq99l4209R0vfP8inQPszF7YI6GilEmRzDaXIH2g9q++eUIY+Al8UxsdG3btorYabOobzPpOdEZ9z3gvz72VCfxCpqLWr/uM7O/50hNk4yInyntyuhK+mqKpOjt2iOVK9Wgzg2kMvfhiZy8fchXP7xccNZINZ7tL3J+N2xMtGfnfLh3JQZyHFHM/Y8XWYGZx51O8pCSWjRzE="
}

Return parameters

Name	Type	Description
status	String	The status of the returned result
code	Integer	Status code of the retured result. 0 means success
data	Object	See below for the description of the data parameter

Description of data parameters

Name	Type	Description
local_id	String	Locally persisted fingerprint on device
root_id	String	Fingerprints generated by device fingerprinting server
env_check	Object	Risk detection item results. If the key is true, it indicates that the rule has been triggered. Otherwise, it means no match.
risk_code	Array(Integer)	Detailed Explanation of Risk Detection Items
ts	Integer	Timestamp of server
client_ts	Integer	Timestamp generated by the client-side data.

Description of env_check parameters

Name	Type	Client Type	Description
is_simulator	Boolean	Android, iOS, Web	Whether it is an emulator
is_debug	Boolean	Android, iOS, Web, MiniApp	Whether it is in debugging mode
is_hook	Boolean	Android, iOS, Web	Whether it has been tampered
is_risk_app	Boolean	Android, iOS	Whether it has risky applications installed
is_proxy	Boolean	Android, iOS, MiniApp	Whether it is rooted device
is_multi_open	Boolean	Android, iOS	Whether to support the usage of multiple instances of the application
is_vpn	Boolean	Android, iOS	Whether the VPN is enabled
is_root	Boolean	Android	Whether it is rooted device
is_jailbreak	Boolean	iOS	Whether it is a jailbroken device
is_blacklist_device	Boolean	Android, iOS	Whether it is a blacklisted device
is_incognito	Boolean	Web	Whether it is in incognito mode

Sample Parameters

{
    "status": "success",
    "code": 0,
    "data": {
        "local_id": "247A8CCF15054743B781759621570060",
        "env_check": {
            "is_debug": true,
            "is_simulator": false,
            "is_risk_app": true,
            "is_hook": false,
            "is_jailbreak": false,
            "is_proxy": true,
            "is_multi_open": false,
            "is_blacklist_device": false
        },
        "root_id": "GEE4-01-6d1bd4541d5b9f679cda9086bb3dffaf1f42992917f23f11a63da390ebff6014",
        "sign": "8e9916c5340c43fa003fe2dd54cd4e3027affbfc0d631e4cd858f64ec09fa9ed",
        "ts": 1704958660211,
        "client_ts": 1704958649275,
        "risk_code": [
            21000,
            20400,
            20210,
            20501,
            90106
        ],
        "ip_type": 1
    }
}

Description of risk_code

Client-side risk code	Risk code Description	Scenario Risk Description	Client Type
10001	Detected package tampering or repackaging	Some malicious actors may tamper with application packages to add advertisments or modify business logic, then repacakage and release them.	Android, iOS, Web
10002	GeeToken expired or reused, GeeToken valid for 10 minutes	Illicit actors may cache and accumulate tokens, exploiting them in large-scale requests to business API with a short period at the onset of an activity.	Android, iOS, Web
20100	Detected Traditional Emulator Risk	The black market exploits traditional emulators to carry out large-scale illicit operations, such as mass registration, bulk login attacks, and other activities.	Android, iOS, Web
20101	Detected ARM Emulator (or cloud-based mobile devices) risk	Malicious actors exploit ARM emulators (or cloud-based mobile devices) to achieve more efficient and automated illicit operations compared to previous technologies. This includes mass registration, large-scale login credential-stuffing attacks, and other activities conducted on a mass scale.	Android
20103	Detected risk of running App on Mac	Black and gray market activities exploit the automation and tampering features of M chip Macs to carry out related malicious behaviors.	iOS
20200	Detected risk of installed multi-instance tools for the device	In scenarios like malicious actors create multiple app clones on the same device during marketing campaigns, logging into various accounts, and collabrate to complete the invitation process in order to obtain related promotional rewards.	Android
20201	Detected the risk of device being installed with device tampering tools	In order to evade detection by risk control tools, cybercriminals may alter certain device information and attributes, such as changing the IMEI and other device identifiers, to avoid being marked by device fingerprinting	Android, iOS
20202	Detected the risk of group control/automation tools, enabling large-scale malicious operations	Efficiently control multiple devices to perform large-scale operations, such as liking, forwarding, and mass advertising.	Android, iOS
20203	Detected the risk of using reverse engineering tools	Malicious actors may employ reverse engineering tools to deconstruct the application’s business logic, and subsequently, alter the code.	Android, iOS, Web
20204	Detected the risk of using network tampering tools on the device	Malicious actors typically exploit such tools to modify networks to achieve their attack objectives, such as evading the tracking and detection of risk control systems at the network identification level.	Android, iOS
20205	Detected the risk of using game modification tools	Farmers or cheating players may use such tools to cheat in games.	Android, iOS
20206	Detected the risk of virtual location	Malicious actors often tamper with location information to evade location-based restrictions or simulate human-like movement patterns	Android, iOS
20207	Currently in an Android virtual machine environment	Malicious actors can create a new virtual environment on Android devices. It supports various automated attacks such as automated ordering automatic upgrades, and automatic follower requests.	Android
20210	Currently running in a multi-instance environment	Malicious actors can use the device’s built-in clone apps to run multiple instances and facilitate multiple account login and collabrations.	Android, iOS
20211	Currently using device modification or risk tools	In order to evade detection by risk control tools, black-hat actors may modify certain device information and attributes, such as changing the IMEI and other device identifiers, to escape the marking of device fingerprints.	Android
20212	Currently utilizing group control or automation tools	Efficiently control multiple devices, enabling scalable operations such as liking, forwarding, and mass advertising	Android, iOS
20213	Currently employing reverse engineering and tampering tools	The black market may employ reverse engineering tools to analyze the business logic of applications, subsequently tampering with the code.	Android
20216	Currently utilizing virtual location tools	The black industry often manipulates location information to evade location-based restrictions in operations or falsifies trajectories to simulate genuine human behavior.	Android, iOS
20300	The device has a low risk of code tampering, this label requires excluding behavior related to self-developed tampering.	There is a suspicion of code tampering, which could be indicative of illicit tampering activities, or it may involve developers utilizing tampering techniques during the development process.	iOS
20301	Moderate-risk code tampering on the device, possible tampering of code logic.	There is code tampering behavior, where malicious actors alter the code logic to attack business API, aiming to achieve certain profit motives.	Android, iOS
20302	High-risk of code tampering on the device	Engages in high-risk of code tampering activities, employing potentially risky tampering techniques.	Android, iOS
20303	There is a risk of information forgery for the device, where the device attributes or fingerprints do not match.	Illicit actors may forge certain device information, allowing the current device to masquerade as a new one, thereby circumventing business restrictions and engaging in gray-hat activities.	Android, iOS
20400	There is a risk of being debugged, allowing for reverse analysis, cracking, and automated mass control.	Typically, black hat actors use debugging techniques for reverse engineering and breaking into APIs, and other scenarios.	Android, iOS, Web
20401	The device is in debugging mode or is using a debug version of the application package.	This characteristic is often associated with debugging, group control, or hacking activities, and there are cases where inadvertent activation of developer mode by some regular users may also result in a match.	Android, iOS
20402	The device is screen sharing.	Attackers may deceive users into enabling screen sharing to obtain personal information, ultimately leading to financial loss.	iOS
20500	VPN is active on the device	When the device activates a VPN, there is a risk of tampering at the network level, allowing evasion of network identification tracking and potential alteration of the network.	Android, iOS
20501	Network proxy is active on the device	The device engages in network proxy behavior, accessing specified exits through system proxies to evade detection and restrictions imposed by risk control systems.	Android, iOS
20600	Jailbreaking activities detected on iOS devices.	Jailbreaking an iOS device grants higher privileges, allowing for more advanced manipulation of business operations.	iOS
20601	Root behavior detected on Android device	Root an Android device grants higher privileges, allowing for more advanced manipulation of business operations.	Android
20602	The Android device is utilizing a suspicious custom ROM.	Some black and gray market devices are equipped with ROMs customized on the Android Open Source Project, exhibiting strong camouflage capabilities and posing a significant threat to business integrity due to the potential unreliability of the device system.	Android
20603	The Android device ROM based on the Android Open Source Project	Normal Android devices come with manufacturer-specific native systems, while some illicit devices utilize the Android open-source system, posing a certain level of disruptive risk to business operations; the device’s system risk is considered suspicious.	Android
20607	The device’s Bootloader has been unlocked	Once the attacker unlocks the Bootloader, its protection mechanisms are easily bypassed, making it easier for malicious software and attackers to gain control of the device.	Android
20610	The device system version is too low.	Most devices utilized by the majority of illicit activities in the gray-black market are relatively outdated, featuring lower performance and running on older system versions, for example, keeping the system version below Android 9 and iOS 11.	Android, iOS
21000	Device detected without inserted SIM card.	Devices of legitimate users typically use carrier SIM cards, while cardless devices accessing services often originate from gray or black hat devices walls and device farms.	Android, iOS
40001	User ID blacklist	The user ID was manually added to the blacklist.	Android, iOS, Web
40002	IP blacklist	The IP was manually added to the blacklist.	Android, iOS, Web
40003	Device fingerprinting blacklist	The device fingerprinting was manually added to the blacklist.	Android, iOS, Web
60111	User ID whitelist	The user ID was manually added to the whitelist.	Android, iOS, Web
60112	IP whitelist	The IP was manually added to the whitelist.	Android, iOS, Web
60113	Device fingerprinting whitelist	The device fingerprinting was manually added to the whitelist.	Android, iOS, Web
40201	The IP shows malicious cracking or crawling behavior	The IP address has a history of malicious hacking or web crawling activities.	Android, iOS, Web
40202	IP shows malicious attack behavior	The IP address has a history of malicious activities.	Android, iOS, Web
40204	IP suspected to be a proxy IP	IP suspected to be a proxy IP	Android, iOS, Web