Fraud Alerts API — Retrieve and Manage Fraud Alerts

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

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

string

Filter by severity level. Accepted values: low, medium, high, critical. Critical alerts indicate an active, high-volume attack pattern.

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

string

Filter to alerts that include a specific user in their affected scope. Useful when investigating a compromised account.

string

ISO 8601 timestamp. Returns only alerts created at or after this time.

string

ISO 8601 timestamp. Returns only alerts created before or at this time.

integer

default:"20"

Number of results to return per page. Accepted range: 1–100.

string

Pagination cursor. Pass the next_cursor value from a previous response to fetch the next page.

Response Fields

array

Ordered list of alert objects, sorted by created_at descending.

Show Alert object fields

string

Unique identifier for this alert. Use this ID when acknowledging or resolving the alert via PATCH /v1/alerts/{id}.

string

The fraud pattern category that triggered the alert. Matches the alert_type filter values listed above.

string

Severity of the detected pattern: low, medium, high, or critical. Severity is calculated from signal confidence, affected volume, and potential financial exposure.

string

Current lifecycle status of the alert: open, acknowledged, or resolved.

integer

The number of distinct users involved in the detected pattern.

integer

The number of transactions associated with this alert.

string

A human-readable description of the fraud pattern, generated by FraudEG’s detection engine.

string

ISO 8601 timestamp recording when the alert was first triggered.

string

ISO 8601 timestamp of the most recent status change or update to the alert.

boolean

true if additional pages of results exist beyond this response.

string | null

Opaque cursor for fetching the next page. Pass this as the after query parameter. Returns null on the last page.

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.

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.

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

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"

Response

{
  "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
}

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.

Overview

Transactions

Identity

Monitoring

Fraud Alerts API — Retrieve and Manage Fraud Alerts

Endpoint

Query Parameters

Response Fields

Managing Alert Status

Acknowledge an alert

Resolve an alert

Examples

Response

​Endpoint

​Query Parameters

​Response Fields

​Managing Alert Status

​Acknowledge an alert

​Resolve an alert

​Examples

​Response

Endpoint

Query Parameters

Response Fields

Managing Alert Status

Acknowledge an alert

Resolve an alert

Examples

Response