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

# Policy Impact Preview

> Preview the impact of a proposed contact policy before deployment by analyzing how many customers would be affected.

## POST /api/v1/contact-policies/impact-preview

Previews the customer impact of a proposed contact policy configuration. Samples customers from recent interaction history and simulates how many would be affected by the proposed frequency cap.

### Request Body

| Field                 | Type    | Required | Description                                                                        |
| --------------------- | ------- | -------- | ---------------------------------------------------------------------------------- |
| `policyType`          | string  | Yes      | Policy type identifier                                                             |
| `scope`               | string  | No       | Scope: `global`, `offer`, `category`, or `channel` (default: `global`)             |
| `scopeId`             | string  | No       | ID of the scoped entity (required when scope is `offer`, `category`, or `channel`) |
| `config.maxFrequency` | integer | Yes      | Maximum allowed contacts per period (minimum: 1)                                   |
| `config.periodDays`   | integer | Yes      | Lookback period in days (1-365)                                                    |
| `config.outcomeType`  | string  | Yes      | Interaction type to count (e.g., `impression`, `click`, `convert`)                 |
| `sampleSize`          | integer | No       | Max customers to analyze (100-10000, default: 1000)                                |

### Example

```bash theme={null}
curl -X POST https://playground.kaireonai.com/api/v1/contact-policies/impact-preview \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "policyType": "frequency_cap",
    "scope": "channel",
    "scopeId": "ch_email",
    "config": {
      "maxFrequency": 3,
      "periodDays": 7,
      "outcome": "impression"
    },
    "sampleSize": 2000
  }'
```

### Response

```json theme={null}
{
  "totalCustomersAnalyzed": 2000,
  "customersAffected": 420,
  "affectedPercent": 21.0,
  "offersSuppressed": {
    "Platinum Card Upgrade": 85,
    "Auto Loan Refinance": 62,
    "Savings Account Promo": 45
  },
  "avgOffersBeforePolicy": 4.2,
  "avgOffersAfterPolicy": 2.8,
  "topAffectedSegments": [
    { "segment": "High Value", "affected": 180, "total": 500 },
    { "segment": "Active Traders", "affected": 95, "total": 320 }
  ]
}
```

### Response Fields

| Field                    | Type    | Description                                       |
| ------------------------ | ------- | ------------------------------------------------- |
| `totalCustomersAnalyzed` | integer | Number of customers in the sample                 |
| `customersAffected`      | integer | Customers who would hit the frequency cap         |
| `affectedPercent`        | number  | Percentage of analyzed customers affected         |
| `offersSuppressed`       | object  | Map of offer names to suppression counts          |
| `avgOffersBeforePolicy`  | number  | Average contacts per customer before the policy   |
| `avgOffersAfterPolicy`   | number  | Average contacts per customer after the policy    |
| `topAffectedSegments`    | array   | Segments most impacted (sorted by affected count) |

<Tip>
  Use this endpoint before creating a contact policy to understand which customers and offers will be impacted. High `affectedPercent` values may indicate the policy is too restrictive.
</Tip>

### Roles

admin, editor

See also: [Contact Policies](/api-reference/contact-policies) | [Policy Conflicts](/api-reference/policy-conflicts)