Skip to content

Labels, Lists, and Outcomes

Labels, lists, and outcomes work together:

  • Outcomes are the decisions your rules return (HOLD, RELEASE, CANCEL, and others you define).
  • Labels are the ground truth you apply later (FRAUD, NORMAL, CHARGEBACK).
  • Lists are reusable groups referenced in rules (@blocked_users, @trusted_users, etc.).

If you keep these three clean, your rules become much easier to operate and tune.

Transaction Labels

Labels tell you what actually happened after investigation. They are essential for measuring false positives and false negatives.

Common Label Catalog

ezrules does not auto-create labels for you. Create the names you actually use in your operation through the Labels page or the labels API.

Common examples:

  • FRAUD
  • CHARGEBACK
  • NORMAL

Labeling Methods

  1. Open Labels.
  2. Ensure the label names you use operationally exist (FRAUD, NORMAL, CHARGEBACK, etc.).
  3. Upload transaction_id,label_name rows from the CSV section on the page.
  4. Confirm changes in Analytics.

API alternatives are listed in Automation Appendix below.

Create labels.csv with no header row and exactly two columns (transaction_id,label_name) when using CSV workflows.

Example:

txn_001,FRAUD
txn_002,NORMAL
txn_003,CHARGEBACK

Analytics

Open Analytics (sidebar label) to view:

  • Total labeled events
  • Label trends over time
  • Aggregation windows (1h, 6h, 12h, 24h, 30d)

For a useful first read, set the time range to Last 30 Days so sparse label uploads still form visible trend lines.

30-day label analytics charts

Outcomes

Outcomes are your operational decisions. Rules can only return values that exist in the allowed outcomes set.

Common outcomes include:

  • HOLD for manual review
  • RELEASE for approve/allow
  • CANCEL for decline/block

Why Outcomes Matter

  • They standardize decisioning across rules.
  • They make outcome trends measurable in analytics.
  • They let teams align on operational actions.

Manage Outcomes in UI

  1. Open Outcomes.
  2. Add outcome names you want rules to return.
  3. Remove unused outcomes to keep the set clear.
  4. Open Settings and order outcomes under Outcome Resolution so conflicts resolve predictably.

When multiple rules return different outcomes for the same event, ezrules applies the Outcome Resolution hierarchy and stores the highest-severity resolved_outcome.

Example rule snippet:

if $user_id in @blocked_users:
    return !CANCEL

Use the Dashboard to track outcome volume over time. Start with the 30d aggregation when you want to see whether a decision is trending upward or fading out.

Key analytics endpoint:

  • GET /api/v2/analytics/outcomes-distribution?aggregation=30d

Supported aggregation values: 1h, 6h, 12h, 24h, 30d.

30-day outcome trend charts

Outcome Best Practices

  • Keep outcome names short and stable.
  • Reuse existing outcomes where possible.
  • Review the outcome hierarchy whenever you add a new operational decision.
  • Remove unused outcomes during periodic cleanup.
  • Validate your outcome set before major rule rollouts.

User Lists

User lists are reusable sets of values referenced from rules with @ListName.

Example:

if $user_id in @blocked_users:
    return !CANCEL

Manage Lists in UI

  1. Open User Lists.
  2. Create a list.
  3. Add or remove entries.

Use clear names and keep list ownership explicit (for example, who updates the list and how often).

How They Work Together

Typical analyst loop:

  1. Rule evaluates event and returns an outcome (for example HOLD).
  2. Analyst reviews flagged transactions.
  3. Analyst labels reviewed transactions (FRAUD or NORMAL).
  4. Analytics shows whether current outcomes are too broad or too narrow.
  5. Analyst updates list membership and/or rule logic.

This loop is where most quality improvement happens.

API Endpoints

  • POST /api/v2/labels/mark-event
  • POST /api/v2/labels/upload
  • GET /api/v2/labels
  • GET /api/v2/analytics/labels-summary
  • GET /api/v2/analytics/labels-distribution?aggregation=30d
  • GET /api/v2/user-lists
  • GET /api/v2/outcomes
  • POST /api/v2/outcomes
  • DELETE /api/v2/outcomes/{outcome_name}

See OpenAPI docs at http://localhost:8888/docs for schemas and auth requirements.

Next Steps

Automation Appendix

Use this section when labels/lists are managed by scripts or external systems.

Mark one event via API

curl -X POST http://localhost:8888/api/v2/labels/mark-event \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_123",
    "label_name": "FRAUD"
  }'

Upload labels CSV via API

curl -X POST http://localhost:8888/api/v2/labels/upload \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@labels.csv"