Skip to main content

​
Fraud Review Triage — Run the Response Loop

The Fraud Shield reference covers the payloads, categories, severities, and thresholds. This page is the operational side: how to work a single fraud alert end to end, using the four endpoints that make up the triage lifecycle — the list, the single-alert read, acknowledge, and dismiss. All endpoints below are rooted at https://api.orbit.devotel.io/api/v1/compliance/fraud-reviews. Reads are open to any authenticated member of your organization; writes are restricted to owners and admins.

​
The daily triage loop

  1. Find it. GET /compliance/fraud-reviews with the filters you want — status=open, a severity floor, a category, or a from/to window on detected_at. The list sorts critical-first, newest-first, and each row carries an actionable flag from your thresholds, so the rows you must look at today surface on page one.
  2. Open it. GET /compliance/fraud-reviews/:id for the full row. The id is safe to share with an on-call roster — whoever follows it needs a valid credential, and an id outside your organization returns 404, never someone else’s data.
  3. Acknowledge it. POST /compliance/fraud-reviews/:id/acknowledge moves the alert from open to triaged. That marks “a human is on this” and stops two teammates from independently investigating the same alert. The call is idempotent on an already-triaged row.
  4. Resolve it. Dismiss with POST /compliance/fraud-reviews/:id/dismiss when you close it as a false positive or an accepted risk. If follow-ups belong in your own tooling, stamp the ticket id there — your audit log already records who dismissed the alert, when, and which category it was.
An alert set to escalated is locked for you: Orbit’s operators own resolution of irsf_blocked, suspicious_campaign_send, or voice_deepfake_high_score rows they escalate. You get a 409 back instead of a silent no-op.

​
Status transitions — the valid moves

The ledger recognizes four statuses, and only these moves are legal: Anything outside that table returns 409 with a message naming the blocked transition. That strictness is on purpose: a scripted playbook that hits 409 can stop instead of writing nonsense to the ledger.

​
Thresholds drive the loop, not the other way around

GET and PUT /compliance/fraud-reviews/settings carry two fields — notify_min_severity and muted_categories. They decide which subset of open rows is actionable: true in your list, which shapes every step of the loop above. Set them once, not once per incident: a noisy category like api_key_geo_anomaly either stays muted forever or needs a tuning decision, which is exactly what the threshold control encodes. The contract is documented on Fraud Shield — thresholds adjust the view, never the account.fraud.alert webhook or the in-app notification, and critical alerts stay actionable regardless of your floor.

​
When a dispute needs evidence

Triage answers “who is looking at this.” A carrier chargeback dispute answers “prove the block happened.” For that, export GET /compliance/fraud-reviews/chargeback-evidence.csv over the disputed window: one row per eligible block, the column set a carrier can parse, and the export itself written to your audit log. Use it at the resolve step when the alert you are closing is the kind of traffic a vendor billed you for — SMS pumping / AIT over messaging, Wangiri / toll-fraud over voice. If your org runs a standing incident-response playbook (in PagerDuty, Opsgenie, or an internal wiki), wire these endpoints in as playbook steps: the triage loop runs daily, and the CSV export runs only during a live dispute. Both paths hit the same underlying ledger, so the evidence pack reflects the triage decisions you made on the queue.

​
Roles and scopes

  • Reads (GET on the list, one alert, the thresholds, or the CSV) are open to any authenticated member of your organization — on-call members can investigate without an admin.
  • Writes (acknowledge, dismiss, threshold changes) require the owner or admin role. The ledger records the internal operator id server-side; it is never returned to your side of the API.
  • Every endpoint is scoped to your organization. An id from another organization returns 404 on reads and on both triage writes, so a mistyped id or a leaked id leaks nothing.

​
Where this page sits

  • Fraud Shield — the alerts themselves: categories, severities, statuses, the threshold settings, and the chargeback evidence contract.
  • Fraud caps — the pre-send guard: velocity and daily-spend limits that make the alerts above rarer, and the per-country clamp for expensive destinations.
  • Voice destination auto-blocks — the automatic, self-expiring per-destination voice blocks that land in the same triage queue. A block you acknowledge here is a block that page documents.
The loop is designed to be tenant-owned: Orbit detects, you decide. That split — detection on the platform, response in your hands — is the same posture the rest of the compliance documentation takes.