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.
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: |
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 |
|
Entity | Email Address — extracted from the request body field |
Filter | HTTP Response Status equals |
Rule | Group by IP Address, |
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, |
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, |
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, |
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, |
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.