Recommendations

You can get a risk recommendation for a sensitive action your users want to perform in a risk moment in order to assess the risk level and respond with the suggested mitigation strategy when needed. Fraud Prevention code snippets are used to report telemetry and user actions.

Choose the option that matches your integration path:

• Backend integration: Use the Recommendations API to retrieve a recommendation for a reported action.
• Journey integration: Use the Fraud Level Analysis journey step to evaluate an action and proceed based on the recommendation.

This page describes the various recommendations that may be returned and how you'd use them to protect accounts based on the use case.

You can ask for recommendations for the following types of actions, performed as part of the customer journey:

• login: Monitors user authentication attempts. This is the most common point for detecting account takeover (ATO) attacks, credential stuffing, and unusual login patterns.
• register: Tracks new account creations. Monitoring this action helps prevent the creation of fake or fraudulent accounts that could be used for abuse, spam, or to exploit promotions.
• transaction: A general action for financial events. It's crucial for identifying payment fraud, unauthorized transactions, or suspicious money movements. This can often be used as a generalized category for more specific actions.
• checkout: A specific type of transaction related to completing a purchase. This allows for focused monitoring on payment card fraud, promo abuse, and fraudulent orders.
• password_reset: Watches for attempts to reset a password or recover an account. This is a high-stakes moment, as a successful fraudulent reset grants an attacker full control of the account.
• logout: Reports when a user ends their session. While a lower-risk event than login, monitoring logout can help with session management analytics and identifying unusual session terminations.
• account_details_change: Tracks when a user modifies their profile information, such as changing an email address, phone number, or shipping address. Attackers often change these details to lock the legitimate user out of their account.
• account_details_view: Track access to personal and sensitive account information, which inherently carries a risk of exposure or misuse of sensitive data.
• account_auth_change: Monitors changes to a user's authentication methods, like updating a password, adding a new FIDO2 passkey, or changing multi-factor authentication (MFA) settings. This is a critical action to secure against ATO.
• withdraw: Specifically for monitoring the movement of funds out of an account (e.g., a bank transfer or cryptocurrency withdrawal). This is a direct, high-risk financial action.
• credits_change: Tracks the use or transfer of stored value, such as loyalty points, gift card balances, or in-app credits. This helps prevent the fraudulent depletion of a user's stored assets.

For efficient data analytics, gathering detailed information on the context of each recommendation-triggering action can be beneficial. For example, if your app supports various login methods (e.g. password, OTP, or biometric-based), tracking recommendations for each login method is more valuable than grouping them under a generic login category. Therefore, to help you gather refined insights to better monitor your app, Mosaic allows you to report and track recommendations for custom actions (Admin Portal > Fraud Prevention > Configuration > Actions) and organize recommendations in lists.

Essentially, custom actions are aliases you establish as variations of the standard action types. For example, to monitor each login method—as mentioned in the example above—you could create custom actions such as password_login, otp_login, or biometric_login as aliases of the standard login action type.

To obtain recommendations for custom actions, specify them as the action type when triggering action events. Mosaic's ML model is used to classify custom actions and verifies the match between the triggering action and the configured custom action for each event. For more about reporting actions to trigger recommendations, see our Fraud Prevention guides.

Recommendations tell you how to respond to your user's request to access your application. We create them in real-time by applying our advanced, ML-driven detection capabilities to the given context. This allows us to suggest an accurate approach that protects both your application and the user experience. It also means that we handle all the complexity, so all you need to do is act according to the recommendation we provide.

The following types of recommendations may be returned:

If Fraud Prevention cannot return a model-scored recommendation, a fail-open fallback keeps the user flow available.

The reason code distinguishes two cases:

• Evaluation unavailable (FAIL_OPEN_NOT_EVALUATED): A required service or infrastructure component is unavailable.
• Detection timeout (FAIL_OPEN_DETECTION_TIMEOUT): Detection results aren't ready before the individual request reaches its 300 ms timeout.

Both cases return an allow recommendation with a risk score of 50 and are marked Not Evaluated. They follow the same delivery, storage, and visibility lifecycle as model-scored recommendations. Use the reason code—not the risk score—to identify the cause.

For API integrations, GET /risk/v1/recommendation returns 200 OK using the standard response schema. See the fallback recommendation example.

Use the reason code to trigger a secondary risk check, retain the response for compliance, or alert your operations team. Monitor these codes separately from risk trends because increases can indicate service availability or detection latency issues.

Risk mitigation can be performed by providing a challenge to the user that elevates the trust. Different challenges are more suitable for different use cases. Below are some examples of how you can challenge users based on the action they want to perform.

When a recommendation is returned, the reasons are also provided to explain why the recommendation was returned and provide transparency. The calculation of the risk score also relies on the combination of reasons that contribute to the risk assessment. With filters, you can assess risk over time and track past recommendatons, for example, check previous recommendation reasons issued for the same device.

Top reasons are listed in the recommendation details. The first reason in the list is considered to be the most important and has more weight over others. Hover over each reason to see the detected reason codes. You can fine-tune the weight allocated to each reason in this calculation (see Fine-tune detection sensitivity) or enforce rules overriding recommendations. Below are some of the reason examples:

The reasons might be empty if there is no data matching risk or trust indicators—for example, for a new user account with no geolocation or network risks detected. An empty reasons array doesn't identify a fallback response or necessarily mean that no rules were triggered. Fallback responses always include either FAIL_OPEN_DETECTION_TIMEOUT or FAIL_OPEN_NOT_EVALUATED. For recommendations impacted by rules, the top reason will be a recommendation enforced by a rule (for example, Allow).

Reason codes are visible, searchable, and filterable in Admin Portal > Recommendations. For journey-based integrations, they are also displayed under reasons in the Fraud Level Analysis step output in Journey Analytics. You can also retrieve them for historical actions through the Search Actions API.

Risk signals provide insights on specific indicators such as a proxy or VPN connection being used. You can check what indicators have been verified as well as their state. Unlike reasons that take into account a combination of telemetry data, signals are discrete and focus on specific risk factors.

The context identifies the environment and the setup in which the action occurred, for example, the browser name and version, application name, IP address of the country, and other characterics. Device identifiers included in the context help attribute and recognize devices based on their unique characteristics (device fingerprint, device ID, and device key ID).

Transaction data contains additional details related to payment actions, for example, the payee, currency, and amount.

Here's an example of a challenge recommendation:

{
  "id": "385cd06b527a974982e0560b67123fe2b1b5a39fd98d8d32cdbaca8ec16fd62d",
  "issued_at": 1648028118123,
  "recommendation": {
    "type": "challenge"
  },
  "risk_score": 73.2,
  "context": {
    "action_id": "885cd06b527a97498200560b67123fe221b5a39fd98d8d22cdb7ca8ec16ed62d",
    "action_type": "login",
    "action_performed_at": 1648028118123,
    "device_id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwZGE4ZmZjYy01NmE1LTRmMjgtYThkZi04NDY5MmYwYThmYTAiLCJ2ZXJzaW9uIjoxLCJpYXQiOjE2NTU3OTYzODQ1MzF9.TeGoqlCe_6eWzl9a3-vAumG4Xap8WjwsgcO2-DzGtLg",
    "device_fingerprint": "a3c8f5ea75cb65fcdc3d0452b985f957a46e24afdc912e93dac1e115ecf408e5",
    "device_public_key": "xbrgczakydtjkdndzaaa",
    "device_timestamp": 1726733429054,
    "user_id": "5c4afa75c",
    "application_id": "ece93f4",
    "device_timezone": "America/Los_Angeles",
    "device_platform": "desktop",
    "os_name": "macOS",
    "browser_name": "Chrome"
  },
  "risk_signals": {
    "device": {
      "incognito": false,
      "tampered": false,
      "emulated": true,
      "spoofed": false,
      "tz_mismatch": true
    },
    "network": {
      "vpn": false,
      "tor": true,
      "hosting": false,
      "proxy": true,
      "anonymizer": false
    },
    "behavior": {
      "typing_velocity": 0.867,
      "input_method": [
        "is_paste"
      ],
      "no_user_interaction": true
    }
  },
  "reasons": [
    "BEHAVIOR_BOT",
    "IP_RISKY_REPUTATION",
    "DEVICE_SUSPICIOUS_PLATFORM",
    "PROFILE_DEVICE_NEW"
  ]
}

The following example shows a fallback recommendation returned when detection results aren't ready before an individual recommendation request reaches its 300 ms timeout:

{
  "recommendation": {
    "type": "ALLOW"
  },
  "risk_score": 50,
  "reasons": ["FAIL_OPEN_DETECTION_TIMEOUT"]
}

If the risk evaluation cannot be performed because a required service or infrastructure component is unavailable, the response has the same structure with "reasons": ["FAIL_OPEN_NOT_EVALUATED"].