Documentation
API ReferenceChangelogFAQDashboard

Behavior Monitoring

Detect and react to suspicious behavior in real time.

Behavior Monitoring scores end-user behavior instantly based on how users interact with your platform. It helps you spot suspicious patterns early, apply fraud-prevention rules automatically, and respond dynamically before risk escalates.

To assess user behavior, this service collects data about user platform events, which are the key interactions that reflect a user’s journey on a platform, such as:

  • Logins
  • Sign-ups
  • Settings changes
  • Password updates
  • Custom client-defined events (for instance, 2FA disable request or address change)

These events build a live behavioral profile for each user and continuously update a risk score.

In addition to direct platform interactions, we treat KYC transactions as behavioral signals too, even though users perform them through Sumsub onboarding and verification flows. In many cases they are equivalent to sign-up events, so we evaluate them alongside other platform signals for a fuller risk picture.

How Behavior Monitoring works

Behavior Monitoring evaluates your platform’s signals that reach our system in real time. You have to structure payloads according to API specifications and populate key data fields that include core identifiers, for instance:

  • Captured device via Device Intelligence
  • IP data
  • Email or phone number used for settings updates
  • Custom properties

After receiving user behavior data, our system evaluates those live signals with a powerful rules engine. You can use these signals together with KYC data, AML screening and Transaction Monitoring via applicant risk scoring to build a comprehensive risk profile of the user.

📘

Note

If you already use Transaction Monitoring, you will have access to the same rules functionality.

When risk crosses a threshold you set up with rules, we automatically send a response tailored to the situation. Actions required in the response may include:

Get started with Behavioral Monitoring

To enable Behavioral Monitoring, contact our support team. Once enabled, you must complete a two-step setup process within the Sumsub interface.

Step 1: Send event data

You can send event data using one of the following API methods:

  1. Submit transaction for non-existing applicant
  2. Submit transaction for existing applicant

Request examples:

{
  "txnId": "general0001",
  "txnDate": "2024-04-29 02:30:12+0000",
  "type": "userPlatformEvent",
  "applicant": {
    "type": "individual",
    "externalUserId": "PlatformEvent0001",
    "fullName": "Users Fullname",
    "placeOfBirth": "settlementName",
    "dob": "1995-09-30",
    "address": {
      "country": "CAN",
      "postCode": "123456",
      "town": "usersAddressTown",
      "state": "usersAddState",
      "street": "usersAddSt",
      "subStreet": "usersAddSbSt",
      "flatNumber": "101",
      "buildingNumber": "202",
      "buildingName": "usersAddBuildName",
      "formattedAddress": "postCode, town, state, street, buildingNumber"
    },
    "device": {
      "coords": {
        "lat": -1.7976931348623157,
        "lon": " 1.7976931348623157",
        "accuracy": "10"
      },
      "ipInfo": {
        "ip": "242.1.1"
      },
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9",
      "sessionId": "r-v3-812412m9e12d42",
      "fingerprint": "usersDeviceFing",
      "sessionAgeMs": 18,
      "acceptLang": "en"
    }
  },
  "userPlatformEventInfo": {
    "type": "general"
  },
  "props": {
    "customProperty": "Custom value",
    "dailyOutLimit": "10000"
  }
}

{
  "txnId": "general0001",
  "txnDate": "2024-04-29 02:30:12+0000",
  "type": "userPlatformEvent",
  "applicant": {
    "type": "individual",
    "externalUserId": "PlatformEvent0001",
    "fullName": "Users Fullname",
    "placeOfBirth": "settlementName",
    "dob": "1995-09-30",
    "address": {
      "country": "CAN",
      "postCode": "123456",
      "town": "usersAddressTown",
      "state": "usersAddState",
      "street": "usersAddSt",
      "subStreet": "usersAddSbSt",
      "flatNumber": "101",
      "buildingNumber": "202",
      "buildingName": "usersAddBuildName",
      "formattedAddress": "postCode, town, state, street, buildingNumber"
    },
    "device": {
      "coords": {
        "lat": -1.7976931348623157,
        "lon": " 1.7976931348623157",
        "accuracy": "10"
      },
      "ipInfo": {
        "ip": "242.1.1"
      },
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9",
      "sessionId": "r-v3-812412m9e12d42",
      "fingerprint": "usersDeviceFing",
      "sessionAgeMs": 18,
      "acceptLang": "en"
    }
  },
  "userPlatformEventInfo": {
    "type": "general"
  },
  "props": {
    "customProperty": "Custom value",
    "dailyOutLimit": "10000"
  }
}

Before submitting a transaction, you can also view supported event types.

  1. Open one of the API methods mentioned above.
  2. Scroll to the Body Params.
  3. In type, select userPlatformEvent.
  4. Then open userPlatformEventInfo to see the Event type sent within the transaction.

Step 2: Configure rules

You can use prebuilt rule bundles from the Rules Library tuned to common fraud scenarios. Typical configurations combine:

Alternatively, you can create custom rules to reflect your risk tolerance and workflows using various conditions, thresholds, and event patterns.

📘

Note

For more information on how to install and activate rules, see this article.

Step 3: View results

Results of behavior monitoring rules scoring will be available in response to the API call that you used to create the transaction. You can use it right away for an immediate action.

Additionally, after submitting a transaction, you will receive a webhook indicating transaction status.

You can also view the assessment results and react on Behavior Monitoring statuses using this API method.

Request example:

curl --request GET \
     --url https://api.sumsub.com/resources/kyt/txns/id/one

Updated about 11 hours ago