Annotating the Assessment

Overview

To tune your site specific model, you can send reCAPTCHA IDs back to Google labeled as LEGITIMATE or FRAUDULENT. This additional information will help reCAPTCHA Enterprise perform better for your site over time.

Here is a typical assessment:

{
  'tokenProperties': {
    'valid': True,
    'hostname': 'www.google.com',
    'action': 'homepage',
    'createTime': u'2019-03-28T12:24:17.894Z'
   },
  'riskAnalysis': {
    'score': 0.1,
    'reasons': ['AUTOMATION']
  },
  'event': {
    'token': 'RESPONSE_TOKEN',
    'siteKey': 'SITE_KEY'
   },
  'name': u'assessment-id'
}

The name field is the unique identifier for the assessment. reCAPTCHA Enterprise provides a score at the time of the event, and your site may later have more information to decide if the interaction was legitimate or fraudulent. For example, for a user who successfully authenticates using 2-factor-authentication and received a low reCAPTCHA score, you could annotate the assessment as LEGITIMATE. In another example, where reCAPTCHA score was high but your site determined the interaction was fraudulent or abusive, you could annotate the assessment as FRAUDULENT. In addition to sending annotations for potential assessment errors, sharing annotations for true positives and true negatives will also help improve the performance of reCAPTCHA Enterprise.

API Request

Annotate an assessment using the projects.assessments.annotate method.

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

• assessment-id: name returned from the `projects.assessments.create` call

HTTP method and URL:

POST https://recaptchaenterprise.googleapis.com/v1/assessment-id:annotate

Request JSON body:

{
  "annotation": "LEGITIMATE"
}

To send your request, choose one of these options:

curl

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to your service account private key file path.

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/assessment-id:annotate

PowerShell

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to your service account private key file path.

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/assessment-id:annotate" | Select-Object -Expand Content

You should receive a successful status code (2xx) and an empty response.