Overview
This API reference provides detailed information about Fraudio's API endpoints and how to interact with them.
To interact with our Rules Management API, as mentioned in the Quickstart, you can send HTTPS requests to our central API URL. You can send these requests to the Fraudio root URL (api.fraudio.com) with the route /v1/rules:
https://api.fraudio.com/v1/rules
The Rules Management API is comprised of several endpoints:
- Create a Rule: This endpoint creates a new payment fraud rule.
- List Rules: This endpoint lists all rules.
- List a Rule: This endpoint lists a rule.
- Update a Rule: This endpoint updates a rule.
- Archive a Rule: This endpoint archives a rule.
The Rules Management API also exposes Value List endpoints under the route /v1/value-lists:
https://api.fraudio.com/v1/value-lists
- Create a Value List: This endpoint creates a reusable list of values that rules can reference.
- List Value Lists: This endpoint lists value lists.
- List a Value List: This endpoint lists a value list by ID.
- Update a Value List: This endpoint updates a value list.
- Archive a Value List: This endpoint archives a value list.
What are Rules?
In the context of the Payment Fraud Detection (PFD) product, rules serve as the definitive guiding criteria that can modify the machine learning-derived score of a transaction. These are customer-defined measures that can potentially override the AI's color recommendation based on specific conditions that you set.
Each rule consists of a trigger — a logical expression that matches certain properties of an incoming transaction. For instance, a trigger might be:
transaction.merchant == "suspicious-merchant" && (transaction.mcccode == "1234" || transaction.mcccode == "5678")
Upon the triggering of a rule, a predefined action is taken, such as:
- Allow: The PFD will suggest a green (good) recommendation.
- Review: A yellow (cautionary) recommendation is returned, indicating the need for possible investigation or review.
- Deny: The PFD will return a red (bad) recommendation.
Rules are assigned a priority level, ranging from 1 (highest) to 5 (lowest), to ensure that the most critical rules are evaluated first. In scenarios where multiple rules might be triggered by a single transaction, the rule with the higher priority will determine the outcome. If two rules share the same priority level, the rule that was created first will take precedence, ensuring consistent rule evaluation and action execution.
For a comprehensive list of fields available for defining rule triggers, check out this link.
Every rule defined within the system possesses a status that dictates its current operational state:
-
Enabled: A rule with this status is live and actively evaluates incoming transactions. If its trigger conditions are met, the rule will take the predefined action.
-
Shadow: A rule in Shadow status is evaluated against incoming transactions but does not influence the authorization decision. Instead, it generates an additional risk recommendation alongside the existing decision, allowing clients to monitor how the rule would perform in real conditions. Once validated, the rule can be promoted to Enabled to start taking action.
-
Disabled: This status ensures that the rule remains defined within the system but is not actively evaluating transactions. Essentially, while the rule remains in place, it's in a dormant state and will not influence any transaction evaluation.
-
Archived: An archived rule is one that has been "soft deleted." While it will no longer evaluate or influence transactions, it is retained within the system for historical reference and potential future reactivation.
Rules can be seamlessly transitioned between these statuses based on the evolving needs of the fraud detection strategy. The flexibility of these status options ensures that rules can be optimally managed and utilized based on real-time requirements.
What are Value Lists?
Value Lists are reusable collections of string values — such as card tokens, merchant IDs, account identifiers, or country codes — that you can reference directly in rule triggers.
Instead of maintaining the same values across multiple rules, you manage them once in a Value List and reuse that list wherever needed. This makes large rule configurations easier to maintain, update, and scale.
In the Rule Editor, Value Lists appear after membership operators such as in and !in. For example, a trigger can check whether a card token belongs to a blocked-card list, without embedding every value in the rule itself.
Each value list has:
- displayName: A human-readable name shown in the portal.
- slug: A stable identifier used when referencing the list from a rule. If you omit it on create, it is derived from the display name.
- entries: The list of string values. Exact-match lists support up to 5000 entries.
- matchType: How values are compared.
- status:
enabled(available for rules) orarchived(soft-deleted; retained for history).
You cannot archive a value list while non-archived rules still reference it.