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

# Fraud Alerts API — Retrieve and Manage Fraud Alerts

> GET /v1/alerts — list fraud alerts generated by FraudEG's detection engine. Filter by severity, status, and time range to triage active threats.

Alerts are automatically generated by FraudEG's risk engine when it detects sustained or elevated fraud patterns across your account — not just a single suspicious transaction, but correlated activity that suggests a broader attack. Examples include a velocity spike in failed payment attempts, a cluster of new devices exhibiting account-takeover signals, or a pattern consistent with card testing. Unlike individual transaction events, alerts aggregate signals across multiple users or transactions and require your team to investigate and close them. Use this endpoint to list, filter, and triage active alerts in your fraud operations workflow.

## Endpoint

```
GET https://api.fraudeg.com/v1/alerts
```

## Query Parameters

<ParamField query="status" type="string" default="open">
  Filter by alert lifecycle status. Accepted values:

  * `open` — Alert is active and requires attention
  * `acknowledged` — Alert has been seen and is under investigation
  * `resolved` — Alert has been closed with a resolution
</ParamField>

<ParamField query="severity" type="string">
  Filter by severity level. Accepted values: `low`, `medium`, `high`,
  `critical`. Critical alerts indicate an active, high-volume attack pattern.
</ParamField>

<ParamField query="alert_type" type="string">
  Filter by the type of fraud pattern detected. Common values include:

  * `velocity_spike` — Abnormal transaction volume in a short window
  * `new_device_cluster` — Multiple new devices with correlated risk signals
  * `ato_pattern` — Signals consistent with account takeover attempts
  * `card_testing` — Sequential low-value charges probing card validity
  * `identity_abuse` — Reuse or fabrication of identity attributes
</ParamField>

<ParamField query="user_id" type="string">
  Filter to alerts that include a specific user in their affected scope. Useful
  when investigating a compromised account.
</ParamField>

<ParamField query="start_time" type="string">
  ISO 8601 timestamp. Returns only alerts created at or after this time.
</ParamField>

<ParamField query="end_time" type="string">
  ISO 8601 timestamp. Returns only alerts created before or at this time.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of results to return per page. Accepted range: `1`–`100`.
</ParamField>

<ParamField query="after" type="string">
  Pagination cursor. Pass the `next_cursor` value from a previous response to
  fetch the next page.
</ParamField>

## Response Fields

<ResponseField name="data" type="array">
  Ordered list of alert objects, sorted by `created_at` descending.

  <Expandable title="Alert object fields">
    <ResponseField name="alert_id" type="string">
      Unique identifier for this alert. Use this ID when acknowledging or
      resolving the alert via `PATCH /v1/alerts/{id}`.
    </ResponseField>

    <ResponseField name="alert_type" type="string">
      The fraud pattern category that triggered the alert. Matches the
      `alert_type` filter values listed above.
    </ResponseField>

    <ResponseField name="severity" type="string">
      Severity of the detected pattern: `low`, `medium`, `high`, or `critical`.
      Severity is calculated from signal confidence, affected volume, and
      potential financial exposure.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current lifecycle status of the alert: `open`, `acknowledged`, or
      `resolved`.
    </ResponseField>

    <ResponseField name="affected_users" type="integer">
      The number of distinct users involved in the detected pattern.
    </ResponseField>

    <ResponseField name="affected_transactions" type="integer">
      The number of transactions associated with this alert.
    </ResponseField>

    <ResponseField name="summary" type="string">
      A human-readable description of the fraud pattern, generated by
      FraudEG's detection engine.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp recording when the alert was first triggered.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of the most recent status change or update to the
      alert.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean">
  `true` if additional pages of results exist beyond this response.
</ResponseField>

<ResponseField name="next_cursor" type="string | null">
  Opaque cursor for fetching the next page. Pass this as the `after` query
  parameter. Returns `null` on the last page.
</ResponseField>

## Managing Alert Status

Once you retrieve an alert, you can update its status using `PATCH /v1/alerts/{id}`. The request body accepts a JSON object.

### Acknowledge an alert

Send this request to indicate that your team is actively investigating the alert.

```bash theme={null}
curl -X PATCH https://api.fraudeg.com/v1/alerts/alt_8xp3zq77mn \
  -H "Authorization: Bearer $FRAUDEG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "acknowledged"}'
```

### Resolve an alert

Send this request to close the alert and record your resolution findings.

```bash theme={null}
curl -X PATCH https://api.fraudeg.com/v1/alerts/alt_8xp3zq77mn \
  -H "Authorization: Bearer $FRAUDEG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "resolution_notes": "Confirmed card testing attack originating from ASN 12345. Affected cards flagged and issuer notified. IP range blocked via rule rule_ip_block_cdn."
  }'
```

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.fraudeg.com/v1/alerts \
    -H "Authorization: Bearer $FRAUDEG_API_KEY" \
    -H "Content-Type: application/json" \
    --data-urlencode "status=open" \
    --data-urlencode "severity=critical" \
    --data-urlencode "limit=10"
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": [
    {
      "alert_id": "alt_8xp3zq77mn",
      "alert_type": "card_testing",
      "severity": "critical",
      "status": "open",
      "affected_users": 1,
      "affected_transactions": 312,
      "summary": "312 low-value transactions ($0.00–$1.00) submitted from a single device in a 14-minute window against 312 distinct card numbers. Pattern is consistent with automated card testing via a compromised checkout session.",
      "created_at": "2024-06-14T11:05:43Z",
      "updated_at": "2024-06-14T11:05:43Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

<Note>
  Instead of polling this endpoint, subscribe to the **`alert.triggered`**
  webhook event to receive real-time notifications the moment FraudEG generates
  a new alert. Webhook delivery is typically within two seconds of alert
  creation, making it the preferred integration pattern for time-sensitive fraud
  operations.
</Note>