> >

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 ture, 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	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	Whether it is rooted device
is_muti_open	Boolean	Android, iOS	Whether to support the usage of multiple instances of the application
is_vpn	Boolean	Android	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_muti_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
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.
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.
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.
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.
20200	Detected a risk of using 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.
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
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.
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.
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.
20205	Detected the risk of using game modification tools	Farmers or cheating players may use such tools to cheat in games.
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
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.
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.
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.
20212	Currently utilizing group control or automation tools	Efficiently control multiple devices, enabling scalable operations such as liking, forwarding, and mass advertising
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.
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.
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.
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.
20302	High-risk of code tampering on the device	Engages in high-risk of code tampering activities, employing potentially risky tampering techniques.
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.
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.
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.
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.
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.
20600	Jailbreaking activities detected on iOS devices.	Jailbreaking an iOS device grants higher privileges, allowing for more advanced manipulation of business operations.
20601	Root behavior detected on Android device	Root an Android device grants higher privileges, allowing for more advanced manipulation of business operations.
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.
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.
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.
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.
90100	The device is identified as a suspicious customized machine.	Criminal entities often evade detection by risk control systems. In order to manage the costs associated with refreshing devices, they typically modify device information to tailor and disguise themselves as a new device.
40001	User ID blacklist	Manually added user ID on the dashboard
40002	IP blacklist	Manually added IP blacklist on the dashboard
40003	Device fingerprinting blacklist	Manually added Device fingerprinting blacklist on the dashboard
40201	The IP shows malicious cracking or crawling behavior	The IP address has a history of malicious hacking or web crawling activities.
40202	IP shows malicious attack behavior	The IP address has a history of malicious activities.