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

# Cases API — Create and Manage Fraud Investigations

> Use the FraudEG Cases API to create fraud investigation records, link transactions and evidence, and track resolution status across your team.

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

<ParamField body="title" type="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"`.
</ParamField>

<ParamField body="case_type" type="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
</ParamField>

<ParamField body="transaction_ids" type="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}`.
</ParamField>

<ParamField body="user_id" type="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.
</ParamField>

<ParamField body="severity" type="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.
</ParamField>

<ParamField body="notes" type="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`.
</ParamField>

<ParamField body="assignee_id" type="string">
  Your internal analyst ID to assign the case to. The assignee receives a
  `case.updated` webhook event when the case is created.
</ParamField>

***

## GET /v1/cases/{id}

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

<ParamField path="id" type="string" required>
  The case ID returned in the `case_id` field when you created the case via
  `POST /v1/cases`.
</ParamField>

### Response Fields

<ResponseField name="case_id" type="string">
  Unique identifier for this case. Stable and globally unique across your
  account.
</ResponseField>

<ResponseField name="title" type="string">
  The short descriptive title set when the case was created.
</ResponseField>

<ResponseField name="case_type" type="string">
  The fraud investigation category. See `case_type` in the POST request body
  for the full list of values.
</ResponseField>

<ResponseField name="status" type="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
</ResponseField>

<ResponseField name="severity" type="string">
  The severity level assigned to this case: `low`, `medium`, `high`, or
  `critical`.
</ResponseField>

<ResponseField name="transaction_ids" type="array">
  Array of transaction ID strings linked to this case.
</ResponseField>

<ResponseField name="user_id" type="string | null">
  The user ID linked to this case, or `null` if no user is associated.
</ResponseField>

<ResponseField name="events" type="array">
  Append-only audit log of all activity on this case, ordered chronologically.

  <Expandable title="Case event object fields">
    <ResponseField name="action" type="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
    </ResponseField>

    <ResponseField name="actor_id" type="string">
      The ID of the analyst or system that performed this action.
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp recording when this action occurred.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp recording when this case was created.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of the most recent update to this case.
</ResponseField>

## 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.

```bash theme={null}
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

<CodeGroup>
  ```bash Create a Case theme={null}
  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"
    }'
  ```

  ```bash Retrieve a Case theme={null}
  curl https://api.fraudeg.com/v1/cases/case_6t4rwy88kd \
    -H "Authorization: Bearer $FRAUDEG_API_KEY" \
    -H "Content-Type: application/json"
  ```
</CodeGroup>

### GET Response

```json theme={null}
{
  "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"
}
```

<Tip>
  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.
</Tip>

<Note>
  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.
</Note>