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
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
{
"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) |
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.
Roles
admin, editor
See also: Contact Policies | Policy Conflicts
