> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Work a Fraud Shield alert end to end

> Walk one fraud alert from first detection to an exported chargeback evidence pack: open the ledger, inspect the alert, tune which signals surface in your view, acknowledge or dismiss it, and export the CSV your carrier dispute needs.

# Work a Fraud Shield alert end to end

The [Fraud Shield concept page](/compliance/fraud-shield) explains what
the tenant fraud-review ledger is and how its endpoints fit together.
This guide is the task-shaped walkthrough: open **Settings → Compliance
→ Fraud Shield**, work an open alert through acknowledge/dismiss, tune
which severities and categories surface in your view, and pull a
chargeback evidence pack for a carrier dispute. Every step names the
dashboard action and the matching API call, rooted at
`https://api.orbit.devotel.io/api/v1/compliance/fraud-reviews`.

<Note>
  Fraud Shield is tenant-owned. Orbit raises the alerts and keeps the
  `account.fraud.alert` webhook fan-out always-on; acknowledge, dismiss,
  and dispute follow-through are your triage decision. The export you
  hand a carrier is evidence you furnish — Orbit does not assert fraud on
  your behalf in the dispute.
</Note>

## 1. What fires an alert

Each detector category maps to a traffic pattern you can spot on your
own account:

| Category                    | What it looks like in your traffic                                                                                                                                                                                               |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `irsf_blocked`              | International-revenue-share or toll-fraud destinations being dialed or texted — a destination Orbit blocked. Includes SMS pumping / artificial traffic inflation (AIT) over messaging and Wangiri one-ring callbacks over voice. |
| `suspicious_campaign_send`  | A campaign send burst that jumps well past your historical send envelope.                                                                                                                                                        |
| `sim_swap_detected`         | The subscriber identity behind a destination number changed between your request and delivery.                                                                                                                                   |
| `voice_deepfake_high_score` | An inbound or outbound call whose voice-biometric deepfake score crossed the threshold.                                                                                                                                          |
| `api_key_geo_anomaly`       | One of your API keys returned requests from a location your usage history does not show.                                                                                                                                         |
| `spend_velocity_anomaly`    | Wallet spend accelerated past your historical rate — the signature of a drained account.                                                                                                                                         |

Severity runs `low < medium < high < critical`. `critical` alerts always
flag `actionable` regardless of the threshold you set in Step 4.

## 2. Open the ledger

Dashboard: **Settings → Compliance → Fraud Shield** shows the alert
list, the triage thresholds, and the evidence download. Any
authenticated member can read; acknowledge/dismiss and settings writes
need an owner or admin role.

Read the same list over the API:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/compliance/fraud-reviews?status=open&severity=high" \
  -H "Authorization: Bearer $ORBIT_API_KEY"
```

```json theme={null}
{
  "data": {
    "reviews": [
      {
        "id": "frv_01H8E2J4ZKPV3B6P2Q6A9R7D4EF",
        "category": "irsf_blocked",
        "severity": "high",
        "status": "open",
        "summary": "SMS pumping / AIT: 41 sends to +1876 prefix blocked in 5 minutes",
        "details": { "destination_prefix": "+1876", "blocked_count": 41 },
        "source": "messaging",
        "detected_at": "2026-09-09T18:42:11.205Z",
        "triaged_at": null,
        "resolved_at": null,
        "actionable": true
      }
    ],
    "prefs": {
      "notify_min_severity": "low",
      "muted_categories": [],
      "updated_at": "2026-09-08T11:20:03.000Z",
      "updated_by": "usr_admin_01"
    }
  },
  "meta": { "request_id": "req_01H8E2J", "timestamp": "2026-09-10T08:15:00.000Z" }
}
```

The filter parameters are `status`, `severity`, `category`,
`from` / `to` (ISO-8601 bounds on `detected_at`), and `limit` (1–500,
default 100). One alert by id is
`GET /compliance/fraud-reviews/:id`; an id that is not yours returns
404 — cross-tenant reads are impossible by construction.

## 3. Triage it: acknowledge or dismiss

Acknowledge marks an alert `triaged` — you saw it and are investigating.
Dismiss marks it `dismissed` — closed as a false positive or an accepted
risk. Either way the move lands in your audit log with your user id, so
follow-up review can rebuild who decided what:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/fraud-reviews/frv_01H.../acknowledge" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/fraud-reviews/frv_01H.../dismiss" \
  -H "Authorization: Bearer $ORBIT_API_KEY"
```

Rules that fall out of the state machine:

* Re-acknowledging a `triaged` alert is a no-op; re-dismissing a
  `dismissed` alert is a no-op. Both calls are idempotent.
* A `dismissed` or `escalated` alert cannot be acknowledged; an
  `escalated` alert (closed by Orbit's operators) cannot be dismissed.
  Either violation returns a 409 explaining the state.
* The member id behind any triage decision is recorded in your audit
  log but never echoed in the API response.

## 4. Tune the actionable view

Two thresholds decide which alerts flag `actionable: true` in your list
and dashboard:

| Field                 | Type                            | Effect                                                         |      |            |                                                                                         |
| --------------------- | ------------------------------- | -------------------------------------------------------------- | ---- | ---------- | --------------------------------------------------------------------------------------- |
| `notify_min_severity` | enum \`low                      | medium                                                         | high | critical\` | Alerts under the floor flag `actionable: false`. Default `low` — everything actionable. |
| `muted_categories`    | array of category keys (max 12) | Categories you have judged noise; flagged `actionable: false`. |      |            |                                                                                         |

```bash theme={null}
curl -X PUT "https://api.orbit.devotel.io/api/v1/compliance/fraud-reviews/settings" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notify_min_severity": "high", "muted_categories": ["api_key_geo_anomaly"]}'
```

The contract you must not break conceptually: the thresholds shape
**your view only**. They never silence the `account.fraud.alert` webhook
or the in-app notification — that fan-out stays always-on so no one
(including you) can mute the security signal by accident. `critical`
alerts stay actionable regardless of the floor. Write access is
owner/admin only.

## 5. Export a chargeback evidence pack

When an SMS pumping / AIT or Wangiri / toll-fraud burst shows up on a
carrier bill, the dispute wants evidence. Export the blocks Orbit
raised on your account as an RFC-4180 CSV:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/compliance/fraud-reviews/chargeback-evidence.csv?window_days=30" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -OJ
```

`window_days` is the look-back (1–90, default 30). One row per eligible
block with stable columns: `review_id`, `detected_at`, `source`,
`category`, `severity`, `status`, `phone_prefix`, `channel`, `rule`,
`block_category`, `risk_score`, `summary`, `report_generated_at`. No
eligible blocks over the window → a header-only file. Every export is
written to your audit log with the window and eligible row count, so
the export itself is part of your evidence trail.

Two caveats that stay tenant-owned: the file is evidence **you**
furnish to a carrier in a dispute — Orbit does not join the dispute or
assert fraud on your behalf — and Verify (OTP) traffic has its own
dedicated export at `GET /verify/conversion-anomaly/evidence-export.csv`
(the Fraud Shield CSV covers messaging and voice only).

## 6. Worked example — an AIT pumping alert end to end

A 2FA campaign starts spraying verification codes to a premium-rate
prefix; Orbit blocks the sends and raises an
`irsf_blocked` / `high` alert under `status: open`.

1. **List the open high-severity alerts** — the curl from Step 2 returns
   the alert with `actionable: true` and the blocked count in its
   `details` (e.g. a `+1876` prefix with 41 blocked sends).
2. **Inspect it** — `GET /compliance/fraud-reviews/:id` returns the
   same row; confirm the blocked prefix, the `source` (`messaging` or
   `voice`), and the summary.
3. **Suppress future noise from this category (optional)** — if the
   same benign pattern keeps firing, put
   `"muted_categories": ["api_key_geo_anomaly"]` style entries in a
   `PUT /settings` call. For AIT you would suppress nothing; the step
   exists so a one-off category you have judged noisy stops flagging
   `actionable`.
4. **Acknowledge the alert** —
   `POST /compliance/fraud-reviews/:id/acknowledge` flips it to
   `triaged`, records the move in the audit log, and clears the banner.
5. **Export the dispute pack** —
   `GET /compliance/fraud-reviews/chargeback-evidence.csv?window_days=30`
   hands the carrier a row-per-block CSV for the window the charge
   covered. In the dispute this file is yours to submit — Orbit does
   not assert fraud on your behalf.

## Related references

* [Fraud Shield concept page](/compliance/fraud-shield) — endpoint
  summaries, category/severity tables, and the tenant-owned posture
  note this walkthrough applies.
* [API Reference → Compliance](/api-reference/endpoints/compliance) —
  the route schemas the curl examples above call.
* [Webhooks events reference](/webhooks/events) — the
  `account.fraud.alert` webhook your thresholds never gate.