Cases API — Create and Manage Fraud Investigations

Cases are structured investigation records that bring together everything your team needs to investigate and resolve a fraud incident: linked transactions, associated users, analyst notes, status history, and a full audit log of every action taken. When a suspicious pattern warrants deeper investigation — whether triggered by an alert, a chargeback dispute, or a manual review — you create a case to track it from discovery through resolution. Cases give your fraud operations team a shared, persistent record that integrates directly with FraudEG’s event and alert data. This page covers two endpoints:

POST /v1/cases — Create a new fraud investigation case
GET /v1/cases/{id} — Retrieve a case by ID

POST /v1/cases

Create a new case to begin tracking a fraud investigation. You can link transactions and a user at creation time, or add them later via PATCH /v1/cases/{id}.

POST https://api.fraudeg.com/v1/cases

Request Body

string

required

A short, descriptive title for the case. Keep it specific enough for your team to identify the investigation at a glance. Example: "Card testing attack — June 14 checkout endpoint".

string

required

The category of fraud this investigation covers. Accepted values:

payment_fraud — Unauthorized or fraudulent payment transactions
account_takeover — Unauthorized access to a legitimate user account
identity_fraud — Synthetic, stolen, or fabricated identity use
chargeback — Investigation linked to a disputed transaction
policy_violation — Abuse of promotions, referrals, or platform policies

array

An array of transaction ID strings to link to this case at creation time. You can link additional transactions later via PATCH /v1/cases/{id}.

string

The ID of the user this investigation primarily concerns. Linking a user gives your team direct access to that user’s event history from within the case record.

string

default:"medium"

The severity level of this investigation. Accepted values: low, medium, high, critical. Severity affects prioritization in your case queue but does not influence FraudEG’s detection engine.

string

Initial analyst notes to attach to the case at creation. These are recorded as the first entry in the case’s events audit log with action note_added.

string

Your internal analyst ID to assign the case to. The assignee receives a case.updated webhook event when the case is created.

GET /v1/cases/

Retrieve the full record for an existing case, including its current status, all linked transactions, and the complete audit log of case activity.

GET https://api.fraudeg.com/v1/cases/{id}

Path Parameters

string

required

The case ID returned in the case_id field when you created the case via POST /v1/cases.

Response Fields

string

Unique identifier for this case. Stable and globally unique across your account.

string

The short descriptive title set when the case was created.

string

The fraud investigation category. See case_type in the POST request body for the full list of values.

string

Current lifecycle status of the case:

open — Investigation has not started
in_review — Actively being investigated
resolved — Investigation complete with a finding
closed — Case closed without a finding or further action

string

The severity level assigned to this case: low, medium, high, or critical.

array

Array of transaction ID strings linked to this case.

string | null

The user ID linked to this case, or null if no user is associated.

array

Append-only audit log of all activity on this case, ordered chronologically.

Show Case event object fields

string

The type of activity recorded. Common values:

created — Case was first created
note_added — An analyst added a note
status_changed — Case status was updated
assignee_changed — Case was reassigned to a different analyst

string

The ID of the analyst or system that performed this action.

string

ISO 8601 timestamp recording when this action occurred.

string

ISO 8601 timestamp recording when this case was created.

string

ISO 8601 timestamp of the most recent update to this case.

Updating a Case

Use PATCH /v1/cases/{id} to update an existing case. You can change the status, append analyst notes, reassign the case, or link additional transactions. Each change is recorded as a new entry in the case’s events audit log.

curl -X PATCH https://api.fraudeg.com/v1/cases/case_6t4rwy88kd \
  -H "Authorization: Bearer $FRAUDEG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_review",
    "notes": "Confirmed three transactions linked to the same device fingerprint. Escalating to senior analyst.",
    "assignee_id": "analyst_99xz"
  }'

Examples

curl -X POST https://api.fraudeg.com/v1/cases \
  -H "Authorization: Bearer $FRAUDEG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Card testing attack — June 14 checkout endpoint",
    "case_type": "payment_fraud",
    "severity": "critical",
    "transaction_ids": [
      "txn_9d3e1a7c",
      "txn_2b7f4e1a",
      "txn_5c8d3f9b"
    ],
    "user_id": "usr_4f9a2c1d",
    "notes": "312 low-value transactions in 14 minutes. Linked to alert alt_8xp3zq77mn. Blocking device fingerprint fp_x7m3n9q2.",
    "assignee_id": "analyst_42wv"
  }'

curl https://api.fraudeg.com/v1/cases/case_6t4rwy88kd \
  -H "Authorization: Bearer $FRAUDEG_API_KEY" \
  -H "Content-Type: application/json"

GET Response

{
  "case_id": "case_6t4rwy88kd",
  "title": "Card testing attack — June 14 checkout endpoint",
  "case_type": "payment_fraud",
  "status": "in_review",
  "severity": "critical",
  "transaction_ids": [
    "txn_9d3e1a7c",
    "txn_2b7f4e1a",
    "txn_5c8d3f9b"
  ],
  "user_id": "usr_4f9a2c1d",
  "events": [
    {
      "action": "created",
      "actor_id": "analyst_42wv",
      "timestamp": "2024-06-14T11:22:05Z"
    },
    {
      "action": "note_added",
      "actor_id": "analyst_42wv",
      "timestamp": "2024-06-14T11:22:05Z"
    },
    {
      "action": "status_changed",
      "actor_id": "analyst_99xz",
      "timestamp": "2024-06-14T11:45:33Z"
    },
    {
      "action": "assignee_changed",
      "actor_id": "analyst_42wv",
      "timestamp": "2024-06-14T11:45:33Z"
    }
  ],
  "created_at": "2024-06-14T11:22:05Z",
  "updated_at": "2024-06-14T11:45:33Z"
}

When you identify a fraud ring — multiple transactions sharing a common device fingerprint, IP range, or identity attribute — link all of them to a single case. Consolidating evidence in one record gives your analysts a complete picture of the attack’s scope, makes it easier to calculate total exposure, and produces a stronger evidence package for chargebacks or law enforcement referrals.

Subscribe to the case.updated webhook event to receive real-time notifications whenever a case status changes, a note is added, or the case is reassigned. This lets you trigger downstream workflows — such as notifying an analyst via your internal tooling or updating a linked ticket in your issue tracker — without polling the API.

Overview

Transactions

Identity

Monitoring

Cases API — Create and Manage Fraud Investigations

POST /v1/cases

Request Body

GET /v1/cases/

Path Parameters

Response Fields

Updating a Case

Examples

GET Response

​POST /v1/cases

​Request Body

​GET /v1/cases/

​Path Parameters

​Response Fields

​Updating a Case

​Examples

​GET Response

POST /v1/cases

Request Body

GET /v1/cases/

Path Parameters

Response Fields

Updating a Case

Examples

GET Response