# Verifying the user's response

This page explains how to verify a user's response to a reCAPTCHA challenge from your application's
backend.

For web users, you can get the user's response token in one of three ways:

- `g-recaptcha-response` POST parameter when the user submits the form on your site
- [`grecaptcha.getResponse(opt_widget_id)`](https://developers.google.com/recaptcha/docs/display#js_api) after the user completes the reCAPTCHA challenge
- As a string argument to your [callback function](https://developers.google.com/recaptcha/docs/display#render_param) 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()](https://developers.google.com/android/reference/com/google/android/gms/safetynet/SafetyNetApi.RecaptchaTokenResult.html#getTokenResult())
method to get response token if the status returns successful.

## Token Restrictions

Each reCAPTCHA user response token is valid for two minutes, and can only be verified *once* to
prevent replay attacks. If you need a new token, you can re-run the reCAPTCHA verification.

After you get the response token, you need to verify it within two minutes 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 the reCAPTCHA client-side integration on your site. |
| `remoteip` | Optional. The user's IP address. |

## API Response

The response is a JSON object:

    {
      "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. |
| `timeout-or-duplicate` | The response is no longer valid: either is too old or has been used previously. |