Verifying the user's response

This page explains how to verify a user's response to a reCAPTCHA challenge from your application's backend. When a reCAPTCHA is solved by end user, we will return a user response token.

For web users, a new field (g-recaptcha-response) will be populated in HTML and you can get the user’s response in one of three ways:

• g-recaptcha-response POST parameter when the user submits the form on your site
• grecaptcha.getResponse(opt_widget_id) after the user completes the CAPTCHA challenge
• As a string argument to your callback function if data-callback is specified in either the g-recaptcha tag attribute or the callback parameter in the grecaptcha.render method

For Android library users, you can call the SafetyNetApi.RecaptchaTokenResult.getTokenResult() method to get response token if the status returns successful.

Each reCAPTCHA user response token should be used only once. If a verification attempt has been made with a particular token, it cannot be used again. You will need to call grecaptcha.reset() to ask the end user to verify with reCAPTCHA again.

After you get the response token, you need to verify it with reCAPTCHA using the following API to ensure the token is valid.

API Request

URL: https://www.google.com/recaptcha/api/siteverify

METHOD: POST

POST Parameter	Description
secret	Required. The shared key between your site and reCAPTCHA.
response	Required. The user response token provided by reCAPTCHA, verifying the user on your site.
remoteip	Optional. The user's IP address.

API Response

The response is a JSON object, for reCAPTCHA V2 and invisible reCAPTCHA:

{
  "success": true|false,
  "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
  "hostname": string,         // the hostname of the site where the reCAPTCHA was solved
  "error-codes": [...]        // optional
}

For reCAPTCHA Android:

{
  "success": true|false,
  "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
  "apk_package_name": string, // the package name of the app where the reCAPTCHA was solved
  "error-codes": [...]        // optional
}

Error code reference

Error code	Description
missing-input-secret	The secret parameter is missing.
invalid-input-secret	The secret parameter is invalid or malformed.
missing-input-response	The response parameter is missing.
invalid-input-response	The response parameter is invalid or malformed.
bad-request	The request is invalid or malformed.