Annotating an assessment

This page explains how you can provide feedback on the accuracy of the assessments created by reCAPTCHA Enterprise. With this information, reCAPTCHA Enterprise can tune your site-specific model and provide improved performance for your site over time.

Before you begin

Create an assessment.

Understanding when to annotate assessments

reCAPTCHA Enterprise provides a score when creating an assessment that helps you understand the level of risk user interactions pose. Later, when your site has more information about user interactions to determine if the interaction was legitimate or fraudulent, you can confirm or correct reCAPTCHA Enterprise's assessment. To confirm or correct reCAPTCHA Enterprise's assessment, you can send the reCAPTCHA assessment IDs back to Google labeled as LEGITIMATE or FRAUDULENT. Confirming or correcting reCAPTCHA Enterprise's assessment improves the performance of reCAPTCHA Enterprise for your site.

To improve the performance of reCAPTCHA Enterprise, you can confirm the annotations for true positives and true negatives in addition to the annotations for potential assessment errors. For example, for a user who successfully authenticated using a 2-factor-authentication method and received a high reCAPTCHA score, you can annotate the assessment as LEGITIMATE. Alternatively, if reCAPTCHA score was low and your site determined that the interaction was fraudulent or abusive, you can annotate the assessment as FRAUDULENT.

The following list shows additional information about some sample user interactions that indicate whether a user interaction is legitimate or fraudulent:

• Credit card chargebacks or other concrete evidence of fraud indicate that an earlier financial transaction was fraudulent.
• A new account that sends messages that are flagged as spam by other users might indicate that the account creation was fraudulent.
• A support case filed if a user has difficulty logging in to their account might indicate that the login attempt is legitimate.
• A purchase or booking on a site that uses reCAPTCHA Enterprise to defend against scraping might indicate that the user is legitimate.

Retrieving the assessment ID

After you create an assessment, you receive a JSON response as shown in the following example.

To annotate an assessment, retrieve the unique assessment ID from the name field in the JSON response.

{
  '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'
}

Annotating the assessment

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

Note: If you are using the v1beta1 version of the API, we recommend using the v1 version because the new features, such as reCAPTCHA Enterprise account defender are available only on v1 version. For migrating from v1beta1 to v1, see Migrate from v1beta API to v1 API .

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

• ASSESSMENT_ID: Value of the name field returned from the projects.assessments.create call
• ANNOTATION_LABEL: The label to indicate whether the assessment is legitimate or fraudulent. Possible values are LEGITIMATE or FRAUDULENT.
• ANNOTATION_REASON: Describes the context for the annotation that was chosen for this assessment. To learn about possible values, see reasons for annotating an assessment.

HTTP method and URL:

POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate

Request JSON body:

{
"annotation": "ANNOTATION_LABEL"
}

To send your request, choose one of these options:

curl

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

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 the path for your service account private key file.

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.