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

# Fraud Detection

> How AgentRef detects and flags suspicious affiliate activity automatically.

AgentRef automatically monitors affiliate activity and flags suspicious patterns. You decide what to do with each flag.

## How It Works

AgentRef analyzes clicks, conversions, and affiliate behavior in real-time. When something looks suspicious, a **fraud flag** is created for your review.

### Flag Types

| Flag Type                  | What It Detects                                        |
| -------------------------- | ------------------------------------------------------ |
| Suspicious click patterns  | Unusual click volume or timing from a single affiliate |
| Self-referrals             | Affiliate referring their own purchases                |
| Geographic anomalies       | Clicks from unexpected regions                         |
| Conversion velocity        | Too many conversions in a short time window            |
| Cookie stuffing indicators | Signs of forced cookie injection                       |

### Trust Tiers

Affiliates are assigned trust tiers based on their history:

| Tier         | Behavior                                         |
| ------------ | ------------------------------------------------ |
| **New**      | All conversions require manual review            |
| **Trusted**  | Conversions auto-approved, flags still generated |
| **Verified** | Full auto-approval, reduced monitoring           |

Affiliates move between tiers automatically based on their track record. You can also manually adjust tiers.

## Viewing Flags

### In the Dashboard

Go to your program dashboard → **Fraud Flags** to see all open flags with details about why they were raised.

### Via API

<CodeGroup>
  ```javascript Node.js theme={null}
  // List open flags
  const flags = await client.flags.list({
    programId: 'prg_abc123',
    status: 'open',
  })

  // Get flag statistics
  const stats = await client.flags.stats({
    programId: 'prg_abc123',
  })
  ```

  ```python Python theme={null}
  flags = client.flags.list(
      program_id="prg_abc123",
      status="open",
  )

  stats = client.flags.stats(program_id="prg_abc123")
  ```

  ```bash cURL theme={null}
  # List flags
  curl "https://www.agentref.co/api/v1/flags?programId=prg_abc123&status=open" \
    -H "Authorization: Bearer ak_live_YOUR_KEY"

  # Flag stats
  curl "https://www.agentref.co/api/v1/flags/stats?programId=prg_abc123" \
    -H "Authorization: Bearer ak_live_YOUR_KEY"
  ```
</CodeGroup>

## Resolving Flags

Review each flag and decide whether to dismiss it or take action:

<CodeGroup>
  ```javascript Node.js theme={null}
  // Dismiss a flag (false positive)
  await client.flags.resolve('flag_abc123', {
    resolution: 'dismissed',
  })

  // Confirm fraud and block the affiliate
  await client.flags.resolve('flag_abc123', {
    resolution: 'confirmed',
  })
  ```

  ```bash cURL theme={null}
  curl -X POST "https://www.agentref.co/api/v1/flags/flag_abc123/resolve" \
    -H "Authorization: Bearer ak_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{"resolution": "dismissed"}'
  ```
</CodeGroup>

### Resolution Options

| Resolution  | Effect                                                           |
| ----------- | ---------------------------------------------------------------- |
| `dismissed` | Flag closed, no action taken (false positive)                    |
| `confirmed` | Flag confirmed as fraud – associated conversions can be reversed |

## Webhook Integration

Subscribe to `flag.resolved` webhook events to keep your systems in sync:

```json theme={null}
{
  "type": "flag.resolved",
  "data": {
    "id": "flag_abc123",
    "affiliateId": "aff_def456",
    "type": "suspicious_click_pattern",
    "resolution": "dismissed",
    "resolvedAt": "2026-03-23T14:00:00.000Z"
  }
}
```

<Tip>
  Combine fraud detection with the [Webhooks](/webhooks/overview) integration to automatically update your CRM or alert your team when flags are raised.
</Tip>