REST Resource: projects.assessments

Resource: Assessment

A reCAPTCHA Enterprise assessment resource.

JSON representation 
{
  "name": string,
  "event": {
    object (Event)
  },
  "riskAnalysis": {
    object (RiskAnalysis)
  },
  "tokenProperties": {
    object (TokenProperties)
  },
  "accountVerification": {
    object (AccountVerificationInfo)
  },
  "accountDefenderAssessment": {
    object (AccountDefenderAssessment)
  },
  "privatePasswordLeakVerification": {
    object (PrivatePasswordLeakVerification)
  },
  "firewallPolicyAssessment": {
    object (FirewallPolicyAssessment)
  },
  "fraudPreventionAssessment": {
    object (FraudPreventionAssessment)
  },
  "fraudSignals": {
    object (FraudSignals)
  }
}
Fields
name

string

Output only. Identifier. The resource name for the Assessment in the format projects/{project}/assessments/{assessment}.
event

object (Event)

Optional. The event being assessed.
riskAnalysis

object (RiskAnalysis)

Output only. The risk analysis result for the event being assessed.
tokenProperties

object (TokenProperties)

Output only. Properties of the provided event token.
accountVerification

object (AccountVerificationInfo)

Optional. Account verification information for identity verification. The assessment event must include a token and site key to use this feature.
accountDefenderAssessment

object (AccountDefenderAssessment)

Output only. Assessment returned by account defender when an account identifier is provided.
privatePasswordLeakVerification

object (PrivatePasswordLeakVerification)

Optional. The private password leak verification field contains the parameters that are used to to check for leaks privately without sharing user credentials.
firewallPolicyAssessment

object (FirewallPolicyAssessment)

Output only. Assessment returned when firewall policies belonging to the project are evaluated using the field firewallPolicyEvaluation.
fraudPreventionAssessment

object (FraudPreventionAssessment)

Output only. Assessment returned by Fraud Prevention when TransactionData is provided.
fraudSignals

object (FraudSignals)

Output only. Fraud Signals specific to the users involved in a payment transaction.

Event

The event being assessed.

JSON representation 
{
  "token": string,
  "siteKey": string,
  "userAgent": string,
  "userIpAddress": string,
  "expectedAction": string,
  "hashedAccountId": string,
  "express": boolean,
  "requestedUri": string,
  "wafTokenAssessment": boolean,
  "ja3": string,
  "headers": [
    string
  ],
  "firewallPolicyEvaluation": boolean,
  "transactionData": {
    object (TransactionData)
  },
  "userInfo": {
    object (UserInfo)
  }
}
Fields
token

string

Optional. The user response token provided by the reCAPTCHA Enterprise client-side integration on your site.
siteKey

string

Optional. The site key that was used to invoke reCAPTCHA Enterprise on your site and generate the token.
userAgent

string

Optional. The user agent present in the request from the user's device related to this event.
userIpAddress

string

Optional. The IP address in the request from the user's device related to this event.
expectedAction

string

Optional. The expected action for this type of event. This should be the same action provided at token generation time on client-side platforms already integrated with recaptcha enterprise.
hashedAccountId
(deprecated)

string (bytes format)

Optional. Deprecated: use userInfo.account_id instead. Unique stable hashed user identifier for the request. The identifier must be hashed using hmac-sha256 with stable secret.

A base64-encoded string.
express

boolean

Optional. Flag for a reCAPTCHA express request for an assessment without a token. If enabled, siteKey must reference a SCORE key with WAF feature set to EXPRESS.
requestedUri

string

Optional. The URI resource the user requested that triggered an assessment.
wafTokenAssessment

boolean

Optional. Flag for running WAF token assessment. If enabled, the token must be specified, and have been created by a WAF-enabled key.
ja3

string

Optional. JA3 fingerprint for SSL clients.
headers[]

string

Optional. HTTP header information about the request.
firewallPolicyEvaluation

boolean

Optional. Flag for enabling firewall policy config assessment. If this flag is enabled, the firewall policy will be evaluated and a suggested firewall action will be returned in the response.
transactionData

object (TransactionData)

Optional. Data describing a payment transaction to be assessed. Sending this data enables reCAPTCHA Enterprise Fraud Prevention and the FraudPreventionAssessment component in the response.
userInfo

object (UserInfo)

Optional. Information about the user that generates this event, when they can be identified. They are often identified through the use of an account for logged-in requests or login/registration requests, or by providing user identifiers for guest actions like checkout.

TransactionData

Transaction data associated with a payment protected by reCAPTCHA Enterprise.

JSON representation 
{
  "paymentMethod": string,
  "cardBin": string,
  "cardLastFour": string,
  "currencyCode": string,
  "value": number,
  "shippingValue": number,
  "shippingAddress": {
    object (Address)
  },
  "billingAddress": {
    object (Address)
  },
  "user": {
    object (User)
  },
  "merchants": [
    {
      object (User)
    }
  ],
  "items": [
    {
      object (Item)
    }
  ],
  "gatewayInfo": {
    object (GatewayInfo)
  },
  "transactionId": string
}
Fields
paymentMethod

string

Optional. The payment method for the transaction. The allowed values are:

  • credit-card
  • debit-card
  • gift-card
  • processor-{name} (If a third-party is used, for example, processor-paypal)
  • custom-{name} (If an alternative method is used, for example, custom-crypto)
cardBin

string

Optional. The Bank Identification Number - generally the first 6 or 8 digits of the card.
cardLastFour

string

Optional. The last four digits of the card.
currencyCode

string

Optional. The currency code in ISO-4217 format.
value

number

Optional. The decimal value of the transaction in the specified currency.
shippingValue

number

Optional. The value of shipping in the specified currency. 0 for free or no shipping.
shippingAddress

object (Address)

Optional. Destination address if this transaction involves shipping a physical item.
billingAddress

object (Address)

Optional. Address associated with the payment method when applicable.
user

object (User)

Optional. Information about the user paying/initiating the transaction.
merchants[]

object (User)

Optional. Information about the user or users fulfilling the transaction.
items[]

object (Item)

Optional. Items purchased in this transaction.
gatewayInfo

object (GatewayInfo)

Optional. Information about the payment gateway's response to the transaction.
transactionId

string

Unique identifier for the transaction. This custom identifier can be used to reference this transaction in the future, for example, labeling a refund or chargeback event. Two attempts at the same transaction should use the same transaction id.

Address

Structured address format for billing and shipping addresses.

JSON representation 
{
  "recipient": string,
  "address": [
    string
  ],
  "locality": string,
  "administrativeArea": string,
  "regionCode": string,
  "postalCode": string
}
Fields
recipient

string

Optional. The recipient name, potentially including information such as "care of".
address[]

string

Optional. The first lines of the address. The first line generally contains the street name and number, and further lines may include information such as an apartment number.
locality

string

Optional. The town/city of the address.
administrativeArea

string

Optional. The state, province, or otherwise administrative area of the address.
regionCode

string

Optional. The CLDR country/region of the address.
postalCode

string

Optional. The postal or ZIP code of the address.

User

Details about a user's account involved in the transaction.

JSON representation 
{
  "accountId": string,
  "creationMs": string,
  "email": string,
  "emailVerified": boolean,
  "phoneNumber": string,
  "phoneVerified": boolean
}
Fields
accountId

string

Optional. Unique account identifier for this user. If using account defender, this should match the hashedAccountId field. Otherwise, a unique and persistent identifier for this account.
creationMs

string (int64 format)

Optional. The epoch milliseconds of the user's account creation.
email

string

Optional. The email address of the user.
emailVerified

boolean

Optional. Whether the email has been verified to be accessible by the user (OTP or similar).
phoneNumber

string

Optional. The phone number of the user, with country code.
phoneVerified

boolean

Optional. Whether the phone number has been verified to be accessible by the user (OTP or similar).

Item

Line items being purchased in this transaction.

JSON representation 
{
  "name": string,
  "value": number,
  "quantity": string,
  "merchantAccountId": string
}
Fields
name

string

Optional. The full name of the item.
value

number

Optional. The value per item that the user is paying, in the transaction currency, after discounts.
quantity

string (int64 format)

Optional. The quantity of this item that is being purchased.
merchantAccountId

string

Optional. When a merchant is specified, its corresponding accountId. Necessary to populate marketplace-style transactions.

GatewayInfo

Details about the transaction from the gateway.

JSON representation 
{
  "name": string,
  "gatewayResponseCode": string,
  "avsResponseCode": string,
  "cvvResponseCode": string
}
Fields
name

string

Optional. Name of the gateway service (for example, stripe, square, paypal).
gatewayResponseCode

string

Optional. Gateway response code describing the state of the transaction.
avsResponseCode

string

Optional. AVS response code from the gateway (available only when reCAPTCHA Enterprise is called after authorization).
cvvResponseCode

string

Optional. CVV response code from the gateway (available only when reCAPTCHA Enterprise is called after authorization).

UserInfo

User information associated with a request protected by reCAPTCHA Enterprise.

JSON representation 
{
  "createAccountTime": string,
  "accountId": string,
  "userIds": [
    {
      object (UserId)
    }
  ]
}
Fields
createAccountTime

string (Timestamp format)

Optional. Creation time for this account associated with this user. Leave blank for non logged-in actions, guest checkout, or when there is no account associated with the current user.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
accountId

string

Optional. For logged-in requests or login/registration requests, the unique account identifier associated with this user. You can use the username if it is stable (meaning it is the same for every request associated with the same user), or any stable user ID of your choice. Leave blank for non logged-in actions or guest checkout.
userIds[]

object (UserId)

Optional. Identifiers associated with this user or request.

UserId

An identifier associated with a user.

JSON representation 
{

  // Union field id_oneof can be only one of the following:
  "email": string,
  "phoneNumber": string,
  "username": string
  // End of list of possible types for union field id_oneof.
}
Fields

Union field id_oneof.

id_oneof can be only one of the following:
email

string

Optional. An email address.
phoneNumber

string

Optional. A phone number. Should use the E.164 format.
username

string

Optional. A unique username, if different from all the other identifiers and accountId that are provided. Can be a unique login handle or display name for a user.

RiskAnalysis

Risk analysis result for an event.

JSON representation 
{
  "score": number,
  "reasons": [
    enum (ClassificationReason)
  ],
  "extendedVerdictReasons": [
    string
  ]
}
Fields
score

number

Output only. Legitimate event score from 0.0 to 1.0. (1.0 means very likely legitimate traffic while 0.0 means very likely non-legitimate traffic).
reasons[]

enum (ClassificationReason)

Output only. Reasons contributing to the risk analysis verdict.
extendedVerdictReasons[]

string

Output only. Extended verdict reasons to be used for experimentation only. The set of possible reasons is subject to change.

ClassificationReason

Reasons contributing to the risk analysis verdict.

Enums
CLASSIFICATION_REASON_UNSPECIFIED Default unspecified type.
AUTOMATION Interactions matched 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 Interactions with the site were significantly different than expected patterns.
LOW_CONFIDENCE_SCORE Too little traffic has been received from this site thus far to generate quality risk analysis.
SUSPECTED_CARDING The request matches behavioral characteristics of a carding attack.
SUSPECTED_CHARGEBACK The request matches behavioral characteristics of chargebacks for fraud.

TokenProperties

Properties of the provided event token.

JSON representation 
{
  "valid": boolean,
  "invalidReason": enum (InvalidReason),
  "createTime": string,
  "hostname": string,
  "androidPackageName": string,
  "iosBundleId": string,
  "action": string
}
Fields
valid

boolean

Output only. Whether the provided user response token is valid. When valid = false, the reason could be specified in invalidReason or it could also be due to a user failing to solve a challenge or a sitekey mismatch (i.e the sitekey used to generate the token was different than the one specified in the assessment).
invalidReason

enum (InvalidReason)

Output only. Reason associated with the response when valid = false.
createTime

string (Timestamp format)

Output only. The timestamp corresponding to the generation of the token.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
hostname

string

Output only. The hostname of the page on which the token was generated (Web keys only).
androidPackageName

string

Output only. The name of the Android package with which the token was generated (Android keys only).
iosBundleId

string

Output only. The ID of the iOS bundle with which the token was generated (iOS keys only).
action

string

Output only. Action name provided at token generation.

InvalidReason

Enum that represents the types of invalid token reasons.

Enums
INVALID_REASON_UNSPECIFIED Default unspecified type.
UNKNOWN_INVALID_REASON If the failure reason was not accounted for.
MALFORMED The provided user verification token was malformed.
EXPIRED The user verification token had expired.
DUPE The user verification had already been seen.
MISSING The user verification token was not present.
BROWSER_ERROR A retriable error (such as network failure) occurred on the browser. Could easily be simulated by an attacker.

AccountVerificationInfo

Information about account verification, used for identity verification.

JSON representation 
{
  "endpoints": [
    {
      object (EndpointVerificationInfo)
    }
  ],
  "languageCode": string,
  "latestVerificationResult": enum (Result),
  "username": string
}
Fields
endpoints[]

object (EndpointVerificationInfo)

Optional. Endpoints that can be used for identity verification.
languageCode

string

Optional. Language code preference for the verification message, set as a IETF BCP 47 language code.
latestVerificationResult

enum (Result)

Output only. Result of the latest account verification challenge.
username
(deprecated)

string

Username of the account that is being verified. Deprecated. Customers should now provide the accountId field in event.user_info.

EndpointVerificationInfo

Information about a verification endpoint that can be used for 2FA.

JSON representation 
{
  "requestToken": string,
  "lastVerificationTime": string,

  // Union field endpoint can be only one of the following:
  "emailAddress": string,
  "phoneNumber": string
  // End of list of possible types for union field endpoint.
}
Fields
requestToken

string

Output only. Token to provide to the client to trigger endpoint verification. It must be used within 15 minutes.
lastVerificationTime

string (Timestamp format)

Output only. Timestamp of the last successful verification for the endpoint, if any.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

Union field endpoint.

endpoint can be only one of the following:
emailAddress

string

Email address for which to trigger a verification request.
phoneNumber

string

Phone number for which to trigger a verification request. Should be given in E.164 format.

Result

Result of the account verification as contained in the verdict token issued at the end of the verification flow.

Enums
RESULT_UNSPECIFIED No information about the latest account verification.
SUCCESS_USER_VERIFIED The user was successfully verified. This means the account verification challenge was successfully completed.
ERROR_USER_NOT_VERIFIED The user failed the verification challenge.
ERROR_SITE_ONBOARDING_INCOMPLETE The site is not properly onboarded to use the account verification feature.
ERROR_RECIPIENT_NOT_ALLOWED The recipient is not allowed for account verification. This can occur during integration but should not occur in production.
ERROR_RECIPIENT_ABUSE_LIMIT_EXHAUSTED The recipient has already been sent too many verification codes in a short amount of time.
ERROR_CRITICAL_INTERNAL The verification flow could not be completed due to a critical internal error.
ERROR_CUSTOMER_QUOTA_EXHAUSTED The client has exceeded their two factor request quota for this period of time.
ERROR_VERIFICATION_BYPASSED The request cannot be processed at the time because of an incident. This bypass can be restricted to a problematic destination email domain, a customer, or could affect the entire service.
ERROR_VERDICT_MISMATCH The request parameters do not match with the token provided and cannot be processed.

AccountDefenderAssessment

Account defender risk assessment.

JSON representation 
{
  "labels": [
    enum (AccountDefenderLabel)
  ]
}
Fields
labels[]

enum (AccountDefenderLabel)

Output only. Labels for this request.

AccountDefenderLabel

Labels returned by account defender for this request.

Enums
ACCOUNT_DEFENDER_LABEL_UNSPECIFIED Default unspecified type.
PROFILE_MATCH The request matches a known good profile for the user.
SUSPICIOUS_LOGIN_ACTIVITY The request is potentially a suspicious login event and must be further verified either through multi-factor authentication or another system.
SUSPICIOUS_ACCOUNT_CREATION The request matched a profile that previously had suspicious account creation behavior. This can mean that this is a fake account.
RELATED_ACCOUNTS_NUMBER_HIGH The account in the request has a high number of related accounts. It does not necessarily imply that the account is bad but can require further investigation.

PrivatePasswordLeakVerification

Private password leak verification info.

JSON representation 
{
  "lookupHashPrefix": string,
  "encryptedUserCredentialsHash": string,
  "encryptedLeakMatchPrefixes": [
    string
  ],
  "reencryptedUserCredentialsHash": string
}
Fields
lookupHashPrefix

string (bytes format)

Required. Exactly 26-bit prefix of the SHA-256 hash of the canonicalized username. It is used to look up password leaks associated with that hash prefix.

A base64-encoded string.
encryptedUserCredentialsHash

string (bytes format)

Optional. Encrypted Scrypt hash of the canonicalized username+password. It is re-encrypted by the server and returned through reencryptedUserCredentialsHash.

A base64-encoded string.
encryptedLeakMatchPrefixes[]

string (bytes format)

Output only. List of prefixes of the encrypted potential password leaks that matched the given parameters. They must be compared with the client-side decryption prefix of reencryptedUserCredentialsHash

A base64-encoded string.
reencryptedUserCredentialsHash

string (bytes format)

Output only. Corresponds to the re-encryption of the encryptedUserCredentialsHash field. It is used to match potential password leaks within encryptedLeakMatchPrefixes.

A base64-encoded string.

FirewallPolicyAssessment

Policy config assessment.

JSON representation 
{
  "error": {
    object (Status)
  },
  "firewallPolicy": {
    object (FirewallPolicy)
  }
}
Fields
error

object (Status)

Output only. If the processing of a policy config fails, an error will be populated and the firewallPolicy will be left empty.
firewallPolicy

object (FirewallPolicy)

Output only. The policy that matched the request. If more than one policy may match, this is the first match. If no policy matches the incoming request, the policy field will be left empty.

Status

The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details.

You can find out more about this error model and how to work with it in the API Design Guide.

JSON representation 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Fields
code

integer

The status code, which should be an enum value of google.rpc.Code.
message

string

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.
details[]

object

A list of messages that carry the error details. There is a common set of message types for APIs to use.

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.

FraudPreventionAssessment

Assessment for Fraud Prevention.

JSON representation 
{
  "transactionRisk": number,
  "stolenInstrumentVerdict": {
    object (StolenInstrumentVerdict)
  },
  "cardTestingVerdict": {
    object (CardTestingVerdict)
  },
  "behavioralTrustVerdict": {
    object (BehavioralTrustVerdict)
  }
}
Fields
transactionRisk

number

Output only. Probability of this transaction being fraudulent. Summarizes the combined risk of attack vectors below. Values are from 0.0 (lowest) to 1.0 (highest).
stolenInstrumentVerdict

object (StolenInstrumentVerdict)

Output only. Assessment of this transaction for risk of a stolen instrument.
cardTestingVerdict

object (CardTestingVerdict)

Output only. Assessment of this transaction for risk of being part of a card testing attack.
behavioralTrustVerdict

object (BehavioralTrustVerdict)

Output only. Assessment of this transaction for behavioral trust.

StolenInstrumentVerdict

Information about stolen instrument fraud, where the user is not the legitimate owner of the instrument being used for the purchase.

JSON representation 
{
  "risk": number
}
Fields
risk

number

Output only. Probability of this transaction being executed with a stolen instrument. Values are from 0.0 (lowest) to 1.0 (highest).

CardTestingVerdict

Information about card testing fraud, where an adversary is testing fraudulently obtained cards or brute forcing their details.

JSON representation 
{
  "risk": number
}
Fields
risk

number

Output only. Probability of this transaction attempt being part of a card testing attack. Values are from 0.0 (lowest) to 1.0 (highest).

BehavioralTrustVerdict

Information about behavioral trust of the transaction.

JSON representation 
{
  "trust": number
}
Fields
trust

number

Output only. Probability of this transaction attempt being executed in a behaviorally trustworthy way. Values are from 0.0 (lowest) to 1.0 (highest).

FraudSignals

Fraud signals describing users and cards involved in the transaction.

JSON representation 
{
  "userSignals": {
    object (UserSignals)
  },
  "cardSignals": {
    object (CardSignals)
  }
}
Fields
userSignals

object (UserSignals)

Output only. Signals describing the end user in this transaction.
cardSignals

object (CardSignals)

Output only. Signals describing the payment card or cards used in this transaction.

UserSignals

Signals describing the user involved in this transaction.

JSON representation 
{
  "activeDaysLowerBound": integer,
  "syntheticRisk": number
}
Fields
activeDaysLowerBound

integer

Output only. This user (based on email, phone, and other identifiers) has been seen on the internet for at least this number of days.
syntheticRisk

number

Output only. Likelihood (from 0.0 to 1.0) this user includes synthetic components in their identity, such as a randomly generated email address, temporary phone number, or fake shipping address.

CardSignals

Signals describing the payment card used in this transaction.

JSON representation 
{
  "cardLabels": [
    enum (CardLabel)
  ]
}
Fields
cardLabels[]

enum (CardLabel)

Output only. The labels for the payment card in this transaction.

CardLabel

Risk labels describing the card being assessed, such as its funding mechanism.

Enums
CARD_LABEL_UNSPECIFIED No label specified.
PREPAID This card has been detected as prepaid.
VIRTUAL This card has been detected as virtual, such as a card number generated for a single transaction or merchant.
UNEXPECTED_LOCATION This card has been detected as being used in an unexpected geographic location.

Methods

annotate

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

create

 Creates an Assessment of the likelihood an event is legitimate.