> >

GeeTest Status Monitoring API

Notes

API	Description	Notes
/v1/bypass_status.php	Status monitoring API	1. This is the API monitoring the service availability and it’s independent from the main logic. Use polling request. 2. Mark the service availability as fail if returning non-200 status codes or the request timing out.

If the storage space is sufficient
Send the polling request via bypass API. Getting the status and updating database continuously(Redis is used in the demo. You can choose your own database structure). Before client-side is sending request to GeeTest’s server, check the bypass status and decide to continue to send request or switch to failback mode.
If the storage space is not sufficient
Send request to check bypass status before starting the verfication process.

Overview

Item	Details
Remarks	1. Check the service availability. All the CAPTCHA related requests are covered; 2. Run normal process/bypass mode per network status under the specific CAOTCHA ID as the request is sent along with CAPTCHA ID.
Domain	bypass.geetest.com
Endpoint	/v1/bypass_status.php
full URL	https://bypass.geetest.com/v1/bypass_status.php
Method	GET/POST
Request Header	(POST)Content-Type: application/x-www-form-urlencoded
Parameter format	GET: key-value pair, urlEncode POST: form, urlEncode
Response Header	Content-Type: application/json;charset=UTF-8
Response format	JSON

bypass Query parameters

Name	Type	Required	Description
gt	string	Y	CAPTCHA ID

Sample request parameter
gt=c9c4facd1a6feeb80802222cbb74ca8e

bypass Response parameters

Name	Type	Required	Description
status	string	Y	success: service is fully operational fail: the service is down

Sample response

The resposne is normal：
{"status": "success"}  service is fully operational
{"status": "fail"}  service is down

The response is abnormal：
If the status code is non-200, change the service status as fail

Client/SDK Server Communication API Reference

Overview

Item	Initialization	Secondary Verification
Endpoint	/register	/validate
Sample URL	http://localhost:8080/register	http://localhost:8080/validate
Request method	GET	POST
Request Header		Content-Type: application/x-www-form-urlencoded
Request format	Key-value Pair, urlEncode	Form, urlEncode
Resposne Header	Content-Type: application/json;charset=UTF-8	Content-Type: application/json;charset=UTF-8
Response format	JSON	JSON

/register Initialization request parameter

Name	Type	Required	Description
t	string	Y	timestamp

Sample request parameter
t=1592814394125

/register Initialization resposne parameters

Name	Type	Required	Description
success	int	Y	1:servive is available;0: Failback mode
new_captcha	bool	Y	Wether it’s new version CAPTCHA
challenge	string	Challenge number. The unique identifier for the verification process
gt	string	Y	CAPTCHA ID

Sample response

{
    "success": 1,
    "new_captcha": true,
    "challenge": "2b36836f0b4ec6e6e0225e1da4ccdeb2",
    "gt": "c9c4facd1a6feeb80802222cbb74ca8e"
}

/validate request parameters

Name	Type	Required	Description
result	string	Y	success or fail
version	string	Y	sdk version
msg	string	N	detailed fail message

Sample response

{
    "result": "fail",
    "version": "jave-servlet:3.1.0",
    "msg": "极验二次验证不通过"
}

SDK/GeeTest Server Communication API Reference

Notes

Service status needs to be checked before sending the request to GeeTest’s server. Send the request if the service is available. Otherwise, switch to failback mode.

API Overview

Item	Initialization	Secondary Verification
Endpoint	/register.php	/validate.php
Full URL	https://api.geetest.com/register.php	http://api.geetest.com/validate.php
Method	GET	POST
Request Header		Content-Type: application/x-www-form-urlencoded
Request format	Key-value Pair，urlEncode	Form，urlEncode
Response Header	Content-Type: text/javascript;charset=UTF-8	Content-Type: text/javascript;charset=UTF-8
Response format	JSON	JSON

/register.php request parameter

Name	Type	Required	Description
user_id	string	N	Unique identifier of end user；Send with api1 or api2 for subsequent data analysis and it’s not mandatory if concerning about user privacy. Or encrypt the user id before sending to GeeTest server
client_type	string	N	Client type，web（PC Browser），h5（Mobile browser，including webview），native（native app），unknown
ip_address	string	N	IP address
digestmod	string	Y	Signature algorithm to generate unique identifier. Support MD5 by default
gt	string	Y	CAPTCHA ID
json_format	string	Y	Identifier in JSON format
sdk	string	Y	sdk version

Sample request

user_id=test
&client_type=web
&ip_address=127.0.0.1
&digestmod=md5
&gt=c9c4facd1a6feeb80802222cbb74ca8e
&json_format=1

/register.php response parameter

Name	Type	Required	Description
challenge	string	Y	Challenge number，id is wrong if the string is “0”

Please note：The challenge is the origin number string returned from GeeTest’s server. Use it without being encrypted with private key is not allowed. Refer to demo for detailed steps
Recommend to check demo project for more logics.

Sample response

{
    "challenge": "b324874b39840757544e33bf4b60cb80"
}

/validate.php request parameter

Name	Type	Required	Description
user_id	string	N	Unique identifier of end user；Send with api1 or api2 for subsequent data analysis and it’s not mandatory if concerning about user privacy. Or encrypt the user id before sending to GeeTest server
client_type	string	N	Client type，web（PC Browser），h5（Mobile browser，including webview），native（native app），unknown
ip_address	string	N	IP address
seccode	string	Y	Core process data
challenge	string	Y	Challenge number. The unique identifier for the verification process
json_format	string	Y	Identifier in JSON format
sdk	string	Y	SDK Version
captchaid	string	Y	CAPTCHA id

Sample request

user_id=test
&client_type=web
&ip_address=127.0.0.1
&seccode=f7475f921a41f7ba79ae15e41658627c%7Cjordan
&challenge=5a757e661e70fc8e307326912fee8e2c8u
&json_format=1
&sdk=java-servlet%3A3.1.0
&captchaid=c9c4facd1a6feeb80802222cbb74ca8e

/validate.php response parameter

Name	Type	Required	Description
seccode	string	Y	Verfication result, “false” means the verification failed

Sample resposne

{
    "seccode": "91f80894e06d04a58b158ad721266b67"
}

Reference

FAQ

Server’s error code