Interpret assessments for websites

This page explains how to interpret a score to understand the level of risk that user interactions pose, and take appropriate actions for your site.

reCAPTCHA returns a score for each request based on the interactions with your site, regardless of the key type. After you receive the score from reCAPTCHA, you must interpret the score and take appropriate actions for your site.

Before you begin

Create an assessment for your website.

Interpret the assessment

After your backend submits a user's reCAPTCHA response token to reCAPTCHA, you receive an assessment as a JSON response as shown in the following example.

Note: We recommend using any JSON parsers in the non-strict parsing mode to prevent outages in case of any additional fields being introduced to the JSON response. reCAPTCHA Client Libraries handle additional fields for you.

To interpret an assessment, consider the following parameters:

• valid: indicates whether the provided user response token is valid. When valid = false, the reason is specified in invalidReason. valid = false can also indicate that a user has failed to solve a challenge or there is a siteKey mismatch.
• invalidReason: Reason associated with the response when valid = false.
• action: a user interaction that triggered reCAPTCHA verification.
• expectedAction: the expected action from a user that you specified when creating the assessment.
• score: level of risk the user interaction poses.

• reasons: additional information about how reCAPTCHA has interpreted the user interaction.

  {
   "event":{
      "expectedAction":"EXPECTED_ACTION",
      "hashedAccountId":"ACCOUNT_ID",
      "siteKey":"KEY_ID",
      "token":"TOKEN",
      "userAgent":"(USER-PROVIDED STRING)",
      "userIpAddress":"USER_PROVIDED_IP_ADDRESS"
   },
   "name":"ASSESSMENT_ID",
   "riskAnalysis":{
     "reasons":[],
     "score":"SCORE"
   },
   "tokenProperties":{
     "action":"USER_INTERACTION",
     "createTime":"TIMESTAMP",
     "hostname":"HOSTNAME",
     "invalidReason":"(ENUM)",
     "valid":(BOOLEAN)
   }
  }
  

Verify actions

The JSON response contains the action parameter that you specified for a user interaction when calling execute() and the expectedAction parameter that you specified when creating the assessment.

Verify that action matches the expectedAction. For example, a login action should be returned on your login page. If there is a mismatch, it indicates that an attacker is attempting to falsify actions. You can take actions against the user interaction, such as adding additional verifications or blocking the interaction to prevent any fraudulent activities.

Interpret scores

The scoring system of reCAPTCHA is an expansion from prior versions of reCAPTCHA to allow greater granularity in responses. reCAPTCHA has 11 levels for scores with values ranging from 0.0 to 1.0. The score 1.0 indicates that the interaction poses low risk and is very likely legitimate, whereas 0.0 indicates that the interaction poses high risk and might be fraudulent. Out of the 11 levels, only the following four score levels are available before triggering an automatic security review by adding a billing account to your project: 0.1, 0.3, 0.7, and 0.9.

To request access to 11 score levels, add a billing account to your project.

reCAPTCHA learns by monitoring real traffic on your site. Therefore, scores in a staging environment and within 7 days of implementation might differ from the long-term production scores.

If you installed score-based keys, you can first run reCAPTCHA without taking action and then decide on thresholds by looking at the traffic.

Based on the score, you can take an appropriate action in the context of your site. To protect your site better, we recommend that you take the action in the background instead of blocking traffic.

The following table lists some of the actions you might take:

Use case	Action
homepage	See a cohesive view of your traffic on the admin console while filtering scrapers.
login	With low scores, require MFA 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.

Reason codes

Reason codes are available after triggering an automatic security review by adding a billing account to your project. To request access to reason codes, add a billing account to your project.

Some scores might be returned with reason codes that provide additional information about how reCAPTCHA interpreted the interactions.

The following table lists the reason codes and their descriptions:

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 was received from this site to generate quality risk analysis.

What's next

• To tune your site-specific model, you can send the assessment IDs back to Google to confirm true positives and true negatives, or correct errors. For details, see Annotate assessments.