Skip to main content

​
Work a Fraud Shield alert end to end

The Fraud Shield concept page 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.
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.

​
1. What fires an alert

Each detector category maps to a traffic pattern you can spot on your own 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:
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:
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:
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:
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.