Method: projects.assessments.annotate

Annotates a previously created Assessment to provide additional information on whether the event turned out to be authentic or fradulent.

HTTP request

POST https://recaptchaenterprise.googleapis.com/v1beta1/{name=projects/*/assessments/*}:annotate

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The resource name of the Assessment, in the format "projects/{project_number}/assessments/{assessment_id}".

Request body

The request body contains data with the following structure:

JSON representation 
{
  "annotation": enum (Annotation),
  "reasons": [
    enum (Reason)
  ],
  "hashedAccountId": string
}
Fields
annotation

enum (Annotation)

Optional. The annotation that will be assigned to the Event. This field can be left empty to provide reasons that apply to an event without concluding whether the event is legitimate or fraudulent.
reasons[]

enum (Reason)

Optional. Optional reasons for the annotation that will be assigned to the Event.
hashedAccountId

string (bytes format)

Optional. Optional unique stable hashed user identifier to apply to the assessment. This is an alternative to setting the hashedAccountId in assessments.create, for example when the account identifier is not yet known in the initial request. It is recommended that the identifier is hashed using hmac-sha256 with stable secret.

A base64-encoded string.

Response body

If successful, the response body is empty.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

Annotation

Enum that represents the types of annotations.

Enums
ANNOTATION_UNSPECIFIED Default unspecified type.
LEGITIMATE Provides information that the event turned out to be legitimate.
FRAUDULENT Provides information that the event turned out to be fraudulent.
PASSWORD_CORRECT

Provides information that the event was related to a login event in which the user typed the correct password. Deprecated, prefer indicating CORRECT_PASSWORD through the reasons field instead.
PASSWORD_INCORRECT

Provides information that the event was related to a login event in which the user typed the incorrect password. Deprecated, prefer indicating INCORRECT_PASSWORD through the reasons field instead.

Reason

Enum that represents potential reasons for annotating an assessment.

Enums
REASON_UNSPECIFIED Default unspecified reason.
CHARGEBACK Indicates that the transaction had a chargeback issued with no other details. When possible, specify the type by using CHARGEBACK_FRAUD or CHARGEBACK_DISPUTE instead.
CHARGEBACK_FRAUD Indicates that the transaction had a chargeback issued related to an alleged unauthorized transaction from the cardholder's perspective (for example, the card number was stolen).
CHARGEBACK_DISPUTE Indicates that the transaction had a chargeback issued related to the cardholder having provided their card details but allegedly not being satisfied with the purchase (for example, misrepresentation, attempted cancellation).
REFUND Indicates that the completed payment transaction was refunded by the seller.
REFUND_FRAUD Indicates that the completed payment transaction was determined to be fraudulent by the seller, and was cancelled and refunded as a result.
TRANSACTION_ACCEPTED Indicates that the payment transaction was accepted, and the user was charged.
TRANSACTION_DECLINED Indicates that the payment transaction was declined, for example due to invalid card details.
PAYMENT_HEURISTICS Indicates the transaction associated with the assessment is suspected of being fraudulent based on the payment method, billing details, shipping address or other transaction information.
INITIATED_TWO_FACTOR Indicates that the user was served a 2FA challenge. An old assessment with ENUM_VALUES.INITIATED_TWO_FACTOR reason that has not been overwritten with PASSED_TWO_FACTOR is treated as an abandoned 2FA flow. This is equivalent to FAILED_TWO_FACTOR.
PASSED_TWO_FACTOR Indicates that the user passed a 2FA challenge.
FAILED_TWO_FACTOR Indicates that the user failed a 2FA challenge.
CORRECT_PASSWORD Indicates the user provided the correct password.
INCORRECT_PASSWORD Indicates the user provided an incorrect password.