Interpreting the Assessment

This page explains how, after the token is received by your backend, you can send the token to the reCAPTCHA Enterprise API. For more information about reCAPTCHA Enterprise, see the reCAPTCHA Enterprise overview.

The reCAPTCHA Enterprise API returns a score for each request without user friction. The score is based on interactions with your site and enables you to take an appropriate action for your site.

Before you begin

Complete the steps in the Quickstart to gain access to the API, and then instrument your web pages.

Call the API to extract score and reasons

After the token is received by your backend, you can send the token to the reCAPTCHA Enterprise API. For details, see Creating an Assessment

Here is an example of a completed 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'projects/[PROJECT_NUMBER]/assessments/b6ac310000000000'
}

Interpreting the results

reCAPTCHA Enterprise returns a score (1.0 is very likely a good interaction, 0.0 is very likely a bot). Based on the score, you can take appropriate action in the context of your site. Every site is different, but below are some examples of how you might use the score.

As in the examples below, take action behind the scenes instead of blocking traffic to better protect your site.

Use case Recommendation
homepage See a cohesive view of your traffic on the admin console while filtering scrapers.
login With low scores, require 2-factor-authentication or email verification to prevent credential stuffing attacks.
social Limit unanswered friend requests from abusive users and send risky comments to moderation.
e-commerce Put your real sales ahead of bots and identify risky transactions.

reCAPTCHA Enterprise learns by seeing real traffic on your site. For this reason, scores in a staging environment or soon after implementing may differ from production. As reCAPTCHA Enterprise doesn't ever interrupt the user flow, you can first run reCAPTCHA without taking action and then decide on thresholds by looking at your traffic. By default, you can use a threshold of 0.5.

Tuning your results

To tune your site specific model, you can send reCAPTCHA IDs back to Google labeled as false positives or false negatives. For details, see Annotating an Assessment

Reason Codes

Some scores might be returned with reason codes associated. These codes provide some additional information about why reCAPTCHA Enterprise interpreted the interaction the way it did.

Reason code Description
AUTOMATION The interaction matches the behavior of an automated agent.
UNEXPECTED_ENVIRONMENT The event originated from an illegitimate environment.
TOO_MUCH_TRAFFIC Traffic volume from the event source is higher than normal.
UNEXPECTED_USAGE_PATTERNS The interaction with your site was significantly different from expected patterns.
LOW_CONFIDENCE_SCORE Too little traffic has been received from this site thus far to generate quality risk analysis.