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

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