Skip to main content

​
Overview

Pre-Deployment Intelligence is a suite of five simulation APIs that answer “what if?” questions about proposed configuration changes. Instead of deploying a new policy, qualification rule, or experiment and hoping for the best, you can preview its impact on your actual customer data first. Each API samples real data from your tenant’s interaction history, customer segments, and schema tables to produce quantitative impact estimates. No changes are written — these are read-only analytical queries.
All Pre-Deployment Intelligence endpoints require admin or editor role (except Budget Forecast and Power Calculator, which also allow viewer). Responses are computed on-demand from live data, so execution time scales with sampleSize.

​
Policy Impact Preview

Endpoint: POST /api/v1/contact-policies/impact-preview Previews how a proposed contact policy (frequency cap) would affect your customer base. The API samples recent interaction history and calculates how many customers would hit the frequency cap, which offers would be suppressed, and which segments are most affected.

​
Request Body

{
  "policyType": "frequency_cap",
  "scope": "global",
  "scopeId": null,
  "config": {
    "maxFrequency": 3,
    "periodDays": 7,
    "outcome": "impression"
  },
  "sampleSize": 1000
}
FieldTypeRequiredDefaultDescription
policyTypestringYes—Type of policy being previewed
scopeenumNo"global"Scope of the policy: global, offer, category, or channel
scopeIdstringNonullID of the scoped entity (required when scope is not global)
config.maxFrequencyintegerYes—Maximum interactions allowed in the period
config.periodDaysintegerYes—Length of the frequency window in days (1—365)
config.outcomeTypestringYes—Interaction type to count (e.g., impression, click, convert)
sampleSizeintegerNo1000Number of customers to sample (100—10,000)

​
Response

{
  "totalCustomersAnalyzed": 1000,
  "customersAffected": 142,
  "affectedPercent": 14.2,
  "offersSuppressed": {
    "Premium Card": 89,
    "Cash Back Card": 53
  },
  "avgOffersBeforePolicy": 4.7,
  "avgOffersAfterPolicy": 3.2,
  "topAffectedSegments": [
    { "segment": "High Value", "affected": 67, "total": 312 },
    { "segment": "Early Adopter", "affected": 41, "total": 198 }
  ]
}
FieldDescription
totalCustomersAnalyzedNumber of customers in the sample
customersAffectedCustomers who would hit the frequency cap
affectedPercentPercentage of sampled customers affected
offersSuppressedOffers that would be suppressed, with suppression count per offer
avgOffersBeforePolicyAverage interactions per customer without the policy
avgOffersAfterPolicyAverage interactions per customer with the policy applied
topAffectedSegmentsSegments most impacted, sorted by affected count

​
Qualification Reach Estimator

Endpoint: POST /api/v1/qualification-rules/reach-estimate Estimates how many customers qualify or are excluded by a proposed qualification rule. Queries your actual schema tables to produce reach percentages and field distribution statistics.

​
Request Body

{
  "ruleType": "attribute_condition",
  "field": "credit_score",
  "operator": "gte",
  "value": 720,
  "schema": "customers",
  "sampleSize": 5000
}
FieldTypeRequiredDefaultDescription
ruleTypestringYes—Type of qualification rule
fieldstringYes—Column name in the schema table
operatorenumYes—Comparison operator: eq, neq, gt, gte, lt, lte, in, not_in, contains, not_contains
valuestring / number / boolean / arrayYes—Value to compare against
schemastringYes—Name of the data schema to query
sampleSizeintegerNo1000Number of rows to sample (100—10,000)

​
Response

{
  "totalSampled": 5000,
  "qualifying": 3420,
  "excluded": 1580,
  "qualifyPercent": 68.4,
  "excludedBySegment": [
    { "segment": "Young Adults", "excluded": 892 },
    { "segment": "New Customers", "excluded": 445 }
  ],
  "fieldDistribution": {
    "min": 320.00,
    "max": 850.00,
    "avg": 698.42,
    "median": 712.00,
    "p25": 645.00,
    "p75": 755.00
  }
}
FieldDescription
totalSampledTotal rows sampled from the schema table
qualifyingRows that pass the proposed rule
excludedRows that would be excluded
qualifyPercentPercentage of sampled rows that qualify
excludedBySegmentBreakdown of excluded customers by segment
fieldDistributionStatistical summary of the field values (numeric fields only): min, max, avg, median, p25, p75
Use the fieldDistribution statistics to calibrate your threshold. For example, if the median credit score is 712, a rule requiring gte 720 excludes roughly half your customers. Adjusting to gte 680 (below p25 at 645) would include about 75%.

​
Budget Burn Projector

Endpoint: POST /api/v1/offers/budget-forecast Projects when a budget will be exhausted based on historical conversion rates. Uses interaction history to estimate daily conversion volume and calculate an exhaustion date with a confidence level.

​
Request Body

{
  "offerId": "offer_premium_cc",
  "totalBudget": 50000,
  "costPerConversion": 25,
  "lookbackDays": 30
}
FieldTypeRequiredDefaultDescription
offerIdstringNo—Specific offer to forecast (omit for tenant-wide forecast)
totalBudgetnumberYes—Total budget in currency units
costPerConversionnumberYes—Cost per conversion (must be > 0)
lookbackDaysintegerNo30Historical window for rate estimation (1—365)

​
Response

{
  "totalBudget": 50000,
  "costPerConversion": 25,
  "maxConversions": 2000,
  "historicalConversionRate": 0.0842,
  "estimatedDailyConversions": 12.3,
  "estimatedDaysUntilExhaustion": 163,
  "exhaustionDate": "2026-09-01",
  "confidenceLevel": "high",
  "recommendation": "Budget will last approximately 5.4 months at current conversion rates."
}
FieldDescription
totalBudgetThe budget provided in the request
costPerConversionCost per conversion provided
maxConversionsMaximum conversions the budget can support (totalBudget / costPerConversion)
historicalConversionRateObserved conversion rate from the lookback period
estimatedDailyConversionsProjected daily conversions based on historical data
estimatedDaysUntilExhaustionDays until budget is fully consumed (null if no conversion data)
exhaustionDateProjected date of budget exhaustion
confidenceLevelhigh (14+ days, 50+ conversions), medium (7+ days, 20+ conversions), low, or insufficient_data
recommendationHuman-readable summary with actionable guidance

​
Experiment Power Calculator

Endpoint: POST /api/v1/experiments/power-calculator Calculates the required sample size and estimated duration for an A/B experiment to reach statistical significance. Uses your tenant’s actual traffic volume to estimate how long the experiment will need to run.

​
Request Body

{
  "baselineConversionRate": 0.12,
  "minimumDetectableEffect": 0.02,
  "significanceLevel": 0.05,
  "power": 0.80,
  "trafficSplit": 0.5
}
FieldTypeRequiredDefaultDescription
baselineConversionRatenumberYes—Current conversion rate (0.001—1)
minimumDetectableEffectnumberYes—Smallest effect size you want to detect (0.001—1)
significanceLevelnumberNo0.05Alpha level for the test (0.01—0.20)
powernumberNo0.80Statistical power — probability of detecting a true effect (0.5—0.99)
trafficSplitnumberNo0.5Fraction of traffic to the treatment group (0.1—0.9)

​
Response

{
  "requiredSampleSize": 7842,
  "perVariant": 3921,
  "estimatedDuration": {
    "days": 16,
    "basedOnDailyTraffic": 490
  },
  "recommendation": "With 490 daily decisions, you need ~16 days to reach statistical significance.",
  "sensitivityTable": [
    { "effect": 0.01, "sampleSize": 31368, "days": 64 },
    { "effect": 0.02, "sampleSize": 7842, "days": 16 },
    { "effect": 0.05, "sampleSize": 1254, "days": 3 },
    { "effect": 0.10, "sampleSize": 314, "days": 1 }
  ]
}
FieldDescription
requiredSampleSizeTotal sample size needed across all variants
perVariantRequired sample size per variant
estimatedDuration.daysEstimated days to reach the required sample size
estimatedDuration.basedOnDailyTrafficDaily decision volume used for the estimate (from the last 14 days)
recommendationHuman-readable summary
sensitivityTableSample size and duration at different effect sizes for comparison
The power calculator uses the standard two-proportion z-test formula: n = (Z_alpha + Z_beta)^2 * (p1(1-p1) + p2(1-p2)) / (p2-p1)^2. Traffic split adjustments account for uneven splits, which require larger total sample sizes.

​
Segment Overlap Analyzer

Endpoint: POST /api/v1/segments/overlap Analyzes overlap between two or more customer segments by querying their underlying PostgreSQL views and computing pairwise set intersections. Helps identify redundant segments and targeting conflicts.

​
Request Body

{
  "segmentIds": ["seg_high_value", "seg_early_adopter", "seg_premium"],
  "sampleSize": 5000
}
FieldTypeRequiredDefaultDescription
segmentIdsstring[]Yes—Segment IDs to analyze (2—10 segments)
sampleSizeintegerNo5000Maximum customers to sample per segment (100—50,000)

​
Response

{
  "segments": [
    { "id": "seg_high_value", "name": "High Value", "size": 4200 },
    { "id": "seg_early_adopter", "name": "Early Adopter", "size": 1850 },
    { "id": "seg_premium", "name": "Premium Tier", "size": 920 }
  ],
  "overlaps": [
    { "segments": ["seg_high_value", "seg_early_adopter"], "count": 712, "percent": 38 },
    { "segments": ["seg_high_value", "seg_premium"], "count": 890, "percent": 97 },
    { "segments": ["seg_early_adopter", "seg_premium"], "count": 445, "percent": 48 }
  ],
  "totalUniqueCustomers": 5163,
  "overlapWarnings": [
    "97% of Premium Tier customers are also in High Value — consider merging or adjusting targeting",
    "48% of Premium Tier customers are also in Early Adopter — consider merging or adjusting targeting",
    "38% of Early Adopter customers are also in High Value — consider merging or adjusting targeting"
  ]
}
FieldDescription
segmentsEach segment with its ID, name, and sampled size
overlapsPairwise overlap: segment pair, intersection count, and overlap percentage (relative to the smaller segment)
totalUniqueCustomersTotal unique customers across all segments
overlapWarningsWarnings for segment pairs with 30%+ overlap, with actionable recommendations
Segment overlap queries execute against the segments’ underlying PostgreSQL views. All segments must have materialized views (created during segment refresh). If a segment view does not exist, the API returns a 400 error with a message to refresh the segment first.

Contact Policies

Configure frequency caps and suppression rules previewed by the Policy Impact API.

Qualification Rules

Define eligibility rules estimated by the Reach Estimator.

Algorithms & Models

Scoring models and experiments powered by the Power Calculator.