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

# Report Transaction Risk

> Manually classify a transaction, create a rule-less alert, and attach it to an investigation.

## Overview

Use this endpoint when an analyst confirms that a transaction requires investigation
under an active category such as `FRAUD` or `AML`.

The operation:

* marks the transaction as manually reported and sets `flagged=true`;
* creates an alert without a rule, rule snapshot, or numeric risk score;
* creates a new investigation or attaches the alert to the compatible active investigation
  explicitly selected by the analyst;
* writes transaction and investigation audit events.

It does **not** change the transaction status, execute rules, or create a risk analysis audit.

## Authentication

Requires `transactions:edit`.

## Request body

<ParamField body="category" type="string" required>
  Code of an active investigation category, for example `FRAUD` or `AML`.
</ParamField>

<ParamField body="subjectSide" type="&#x22;origin&#x22; | &#x22;destination&#x22;" required>
  Transaction party that becomes the investigation subject. The selected side must
  reference an entity in the same organization.
</ParamField>

<ParamField body="investigationAction" type="&#x22;create&#x22; | &#x22;consolidate&#x22;" required>
  Whether to create a separate investigation or consolidate into an existing one.
</ParamField>

<ParamField body="investigationId" type="string">
  Required only with `investigationAction="consolidate"`. The investigation must be
  active and match the organization and selected subject. It does not need to share the
  reported category: an investigation accumulates several in `categoriesAffected`.
  Because the alert belongs to a transaction, the investigation must also group
  transaction or combined alerts: investigations scoped to person, company or device,
  and single-alert ones, are rejected with `MANUAL_RISK_INVESTIGATION_INVALID`.
</ParamField>

<ParamField body="isUniqueInvestigation" type="boolean" default="false">
  Applies only with `investigationAction="create"`. When `true`, future alerts will
  not be automatically consolidated into this investigation.
</ParamField>

<ParamField body="reason" type="string">
  Optional analyst justification. Maximum 5,000 characters.
</ParamField>

```json theme={null}
{
  "category": "FRAUD",
  "subjectSide": "origin",
  "investigationAction": "create",
  "isUniqueInvestigation": true,
  "reason": "Confirmed by the fraud operations team after customer review."
}
```

## Response

Returns HTTP `201` when the report is created. Repeating the operation returns HTTP
`200` with `alreadyReported: true` and does not duplicate the alert or investigation.

```json theme={null}
{
  "success": true,
  "alreadyReported": false,
  "transaction": {
    "id": "0f7231f6-ec63-45b6-b329-d477ba111d2d",
    "status": "SUCCESSFUL",
    "flagged": true,
    "manualRiskCategory": "FRAUD",
    "manualRiskReportedAt": "2026-09-09T18:00:00.000Z",
    "manualRiskAlertId": "b1b85d55-0cfa-4c19-b308-9273152cdf86",
    "manualRiskInvestigationId": "da62d25d-e459-4dbc-b072-02ff89f1cf10"
  },
  "alert": {
    "title": "FRAUD DETECTION - TX-83921",
    "alertType": "FRAUD",
    "triggerRuleId": null,
    "riskScore": null
  },
  "investigation": {
    "investigationType": "FRAUD",
    "riskAnalysisAuditId": null,
    "isUniqueInvestigation": true,
    "reused": false
  }
}
```

The transaction keeps direct alert and investigation IDs. This prevents a second
report and lets the user open the linked case from the transaction detail.

The investigation audit can be non-null when the alert is attached to an existing
case that already had a risk analysis. The manual alert remains unlinked to any rule
or audit.

After commit, the operation emits the `investigation_created` or
`investigation_updated` automation event, plus `alert_created`. Active organization
automations using those triggers therefore process manual reports as well.