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