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
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
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.