Creating an assessment

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

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

  • The resolved value of the promise returned by the call to grecaptcha.enterprise.execute
  • g-recaptcha-response POST parameter when the user submits the form on your site
  • 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.enterprise.render method

Each reCAPTCHA user response token can only be assessed once. If you need to assess a subsequent action that the user takes on your site, or if a token expires before an assessment can be created, you will need to call grecaptcha.enterprise.execute() again to generate a new token.

API Request

Create an assessment using the projects.assessments.create method.

Before using any of the request data below, make the following replacements:

  • project-id: your GCP project ID
  • token: token returned from the grecaptcha.enterprise.execute() call
  • key: reCAPTCHA Key associated with the site/app

HTTP method and URL:

POST https://recaptchaenterprise.googleapis.com/v1/projects/project-id/assessments

Request JSON body:

{
  "event": {
    "token": "token",
    "siteKey": "key"
  }
}

To send your request, choose one of these options:

curl

Save the request body in a file called request.json, and execute the following command:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://recaptchaenterprise.googleapis.com/v1/projects/project-id/assessments

PowerShell

Save the request body in a file called request.json, and execute the following command:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/project-id/assessments" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "tokenProperties": {
    "valid": True,
    "hostname": "www.google.com",
    "action": "homepage",
    "createTime": "2019-03-28T12:24:17.894Z"
   },
  "riskAnalysis": {
    "score": 0.1,
    "reasons": ["AUTOMATION"]
  },
  "event": {
    "token": "token",
    "siteKey": "key"
   },
  "name": "projects/project-id/assessments/b6ac310000000000"
}

What's next