--- title: "Common Fraud Detection Scenarios" slug: "rule-templates-and-bot-protection-sample-scenarios" description: "Learn how to detect common fraud patterns such as credential stuffing, account takeover, OTP farming, promo abuse, and referral fraud using Custom Entities and Rule Templates." tags: ["Aggregation Rules", "Fraud Detection"] status: "new" updated: 2026-07-25T16:34:59Z published: 2026-07-25T16:34:59Z canonical: "traceabledocs.document360.io/rule-templates-and-bot-protection-sample-scenarios" --- > ## Documentation Index > Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt > Use this file to discover all available pages before exploring further. # Common Fraud Detection Scenarios Fraud patterns rarely look suspicious at the level of a single request. A failed login, a password reset, a new account with a promo code, each is unremarkable on its own. The signal only becomes visible in aggregate, when you can see how many times something happened, and to whom. Traceable's **Custom Entities** and **Aggregation Rule Templates** are built to surface that signal. Together, they let you track application-specific data across your APIs and define the exact conditions under which that data indicates fraud. ## Understand custom entities When the fraud signal exists in a business-specific field, such as a *passport number,* *beneficiary account*, *wallet ID*, or *OTP destination*, create a custom entity to extract and track that value across your APIs. After defining the entity, configure an aggregation rule template to detect suspicious patterns by grouping requests, applying thresholds within a time window, and specifying the action to take, such as generating an alert or blocking requests. A single custom entity can support multiple aggregation rules for different fraud detection scenarios. For more information, see [Entities for Bot Protection](/v1/docs/entity). --- ## Understand rule templates Rule templates are the policy engine that acts on your Custom Entities. A Rule template defines a rule. For example, if a field, grouped by a dimension, exceeds a threshold of distinct or total values within a time window, Traceable triggers an alert or blocks the request. Every rule template consists of the following four attributes: | Attribute | Description | | --- | --- | | **Target Field** | The entity or attribute being measured, for example, *Card Details, Passport Number*, or *Beneficiary Bank Account.* | | **Function** | The aggregation method: `COUNT` for total occurrences, or `DISTINCT_COUNT` for unique values. `DISTINCT_COUNT` It is effective for detecting enumeration and mule patterns. | | **Group By** | The dimension that anchors the count, for example, is grouping by OTP Destination Mobile, so Traceable tracks how many distinct cards are seen per phone number. | | **Threshold + Window** | The trigger condition, for example, more than *5* distinct values in *24* hours. Traceable supports minutes, hours, and days as the window unit. | --- ## Fraud detection use cases The following five use cases represent fraud patterns common across fintech, e-commerce, and digital services. Each is built using the combination of custom entities and Aggregation Rule Templates described above. ### Credential stuffing Attackers replay large lists of stolen username-password pairs against a login endpoint to identify valid credentials. Each individual attempt resembles a normal failed login. The signal that exposes the attack is the volume of distinct accounts targeted from a single origin. The following table discusses the attributes and description: | Attribute | Description | | --- | --- | | **Endpoint** | `POST /api/auth/login` | | **Entity** | Email Address — extracted from the request body field `email`. | | **Filter** | HTTP Response Status equals `401` — counts only failed authentication attempts. | | **Rule** | Group by IP Address, `DISTINCT_COUNT(Email Address) > 20` in 10 minutes. | | **Trigger** | One IP address attempts login against more than 20 distinct email accounts within 10 minutes. | | **Severity** | High — block the IP address and alert the security team. | A legitimate user fails to log in once, at most a few times. A credential stuffing attempt cycles through a large number of distinct accounts from the same origin. `DISTINCT_COUNT` on the email field captures that breadth, where a standard rate limit would not. ### Account takeover via password reset abuse Attackers submit password reset requests for many accounts in rapid succession from the same device or IP address, either to determine which email addresses are registered (account enumeration) or to lock out legitimate users. The following table explains the attributes and its description: | Attribute | Description | | --- | --- | | **Endpoint** | *POST /api/auth/password-reset* | | **Entity** | Email Address — extracted from the request body field. | | **Filter** | None required — all requests to this endpoint are in scope. | | **Rule** | Group by IP Address, `DISTINCT_COUNT(Email Address) > 15` in 5 minutes. | | **Trigger** | One IP address submits password reset requests for more than 15 distinct email addresses in 5 minutes. | | **Severity** | High — a strong signal of enumeration or targeted takeover; block and investigate. | Password reset requires no credentials, which makes it a common target for enumeration. This rule uses *DISTINCT_COUNT* to capture the breadth of accounts targeted, rather than overall request volume. ### OTP and 2FA bypass via phone number farming A single device or automated script requests one-time passwords (OTPs) for many different phone numbers, typically to identify registered numbers, harvest OTP windows for a SIM-swap attack, or exhaust OTP quotas. The following table explains the attributes and its description: | Attribute | Description | | --- | --- | | **Endpoint** | *POST /api/otp/send* | | **Entity** | Phone Number — extracted from the request body field *phone_number*. | | **Filter** | None required — applies to all OTP send requests. | | **Rule** | Group by Device Fingerprint, `DISTINCT_COUNT(Phone Number) > 5` in 15 minutes. | | **Trigger** | One device fingerprint requests OTPs for more than 5 distinct phone numbers in 15 minutes. | | **Severity** | Medium to High — block and alert; flag the device fingerprint for review. | A legitimate user requests an OTP for their own number, typically once per session. Grouping by device fingerprint and measuring `DISTINCT_COUNT` on phone number surfaces a device cycling through a target list, a pattern that per-number rate limits do not catch. ### Promo and bonus abuse Fraudsters create multiple accounts from the same device or network to repeatedly claim sign-up bonuses, referral rewards, or promotional credits. Each account appears legitimate on its own; the shared device is the signal. The following table explains the attributes and its description: | Attribute | Description | | --- | --- | | **Endpoint** | *POST /api/users/register* | | **Entity** | promo_code — extracted from the request body field *promo_code*. | | **Filter** | *promo_code* is not null — scopes the rule to registrations that use a promotional offer. | | **Rule** | Group by Device Fingerprint, `DISTINCT_COUNT(User ID) > 3` in 24 hours. | | **Trigger** | One device fingerprint creates more than 3 accounts claiming a promo within 24 hours. | | **Severity** | Medium — flag the accounts for manual review and withhold promo credit pending verification. | A legitimate customer registers once per device. Grouping by device fingerprint and counting distinct *User IDs* identifies the multi-account pattern without affecting normal users. ### Referral fraud Fraudsters generate synthetic sign-ups using a single referral code to earn referral bonuses at scale. The referring account creates a network of accounts that trace back to a small pool of devices. The following table explains the attributes and its description: | Attribute | Description | | --- | --- | | **Endpoint** | *POST /api/users/register* | | **Entity** | referral_code — extracted from the request body field *referral_code*. | | **Filter** | *refferal_code* is not null — scopes the rule to referred registrations only. | | **Rule** | Group by Referral Code, `DISTINCT_COUNT(Device Fingerprint) > 5` in 24 hours. | | **Trigger** | One referral code is used across more than 5 distinct device fingerprints within 24 hours. | | **Severity** | Medium — suspend referral payouts and flag the referring account for review. | Organic referrals originate from genuinely different devices. Fabricated referrals trace back to a small, recycled pool of device fingerprints. `DISTINCT_COUNT` on device fingerprint, grouped by referral code, surfaces this pattern directly. --- ## Why this matters Most API security platforms operate on a fixed set of signals, such as IP addresses, user agents, and request rates, and cannot reason about the business logic inside a customer's payloads. Custom Entities and Rule Templates close that gap in the following ways: - **Business-specific, not generic** — Rules are written around your actual data model, including their passport fields, relationship labels, and card tokens. - **Composable** — One entity supports multiple rules, so you can add new fraud hypotheses incrementally without rebuilding the existing configuration. For more information, see [Entities for Bot Protection](/v1/docs/entity).