Rescore Impact Preview

Preview the estimated impact of rescoring all leads before committing to the operation. This helps you understand how rule changes will affect lead scores across your entire lead list.

POST /api/v1/ou/{ouId}/scoring/rescore-preview

Calculate the estimated impact of rescoring all leads based on current rule configuration without modifying actual scores.

Request

curl -X POST "https://api.kenbun.io/api/v1/ou/org-123/scoring/rescore-preview" \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json"

Request Body

No request body required. The preview uses the current active rules for the organization.

Response

Status: 200 OK

{
  "totalLeads": 1234,
  "affectedLeads": 342,
  "estimatedIncreases": 120,
  "estimatedDecreases": 50,
  "estimatedUnchanged": 172,
  "averageScoreChange": 5.3,
  "executionTimeEstimate": "~2 minutes"
}

Response Fields

Field	Type	Description
totalLeads	number	Total number of leads in the organization
affectedLeads	number	Leads whose scores would change after rescoring
estimatedIncreases	number	Leads whose scores would increase
estimatedDecreases	number	Leads whose scores would decrease
estimatedUnchanged	number	Leads whose scores would remain the same
averageScoreChange	number	Average score change across all affected leads (can be negative)
executionTimeEstimate	string	Estimated time to complete the full rescore operation

POST /api/v1/ou/{ouId}/profile-scoring/rescore-preview

Preview the impact of rescoring profile fit scores for all leads.

Request

curl -X POST "https://api.kenbun.io/api/v1/ou/org-123/profile-scoring/rescore-preview" \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json"

Response

Status: 200 OK

{
  "totalLeads": 1234,
  "affectedLeads": 189,
  "estimatedIncreases": 95,
  "estimatedDecreases": 42,
  "estimatedUnchanged": 52,
  "averageScoreChange": 3.8,
  "executionTimeEstimate": "~1 minute"
}

Response fields match the engagement scoring preview.

POST /api/v1/ou/{ouId}/account-scoring/rescore-preview

Preview the impact of rescoring account fit scores.

Request

curl -X POST "https://api.kenbun.io/api/v1/ou/org-123/account-scoring/rescore-preview" \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json"

Response

Status: 200 OK

{
  "totalAccounts": 456,
  "affectedAccounts": 112,
  "estimatedIncreases": 67,
  "estimatedDecreases": 28,
  "estimatedUnchanged": 17,
  "averageScoreChange": 4.2,
  "executionTimeEstimate": "~45 seconds"
}

Response fields match the engagement scoring preview (but refer to accounts instead of leads).

Common Errors

Status	Meaning	Solution
401	Unauthorized	Verify your API credentials are correct
404	Organization unit not found	Confirm the OU ID exists
429	Too many requests	Wait before retrying; preview calculations are resource-intensive
500	Server error	Retry the request; contact support if the error persists

Use Cases

1. Assess Rule Change Impact

Before enabling new rules or adjusting weights, preview how scores will shift:

# 1. Add/modify rules via UI or API
# 2. Preview impact before rescoring
curl -X POST "https://api.kenbun.io/api/v1/ou/org-123/scoring/rescore-preview" \
  -u "CLIENT_ID:CLIENT_SECRET"

# 3. Review response
# {
#   "totalLeads": 1500,
#   "affectedLeads": 420,
#   "estimatedIncreases": 280,
#   "estimatedDecreases": 140,
#   "averageScoreChange": 8.5,
#   "executionTimeEstimate": "~3 minutes"
# }

# 4. If acceptable, proceed with rescore
curl -X POST "https://api.kenbun.io/api/v1/ou/org-123/scoring/rescore"

2. Validate Major Ruleset Overhaul

When rebuilding your entire scoring model, preview helps confirm the changes align with expectations:

# Preview engagement score changes
curl -X POST ".../scoring/rescore-preview" -u "CLIENT_ID:CLIENT_SECRET"

# Preview profile score changes
curl -X POST ".../profile-scoring/rescore-preview" -u "CLIENT_ID:CLIENT_SECRET"

# Preview account score changes
curl -X POST ".../account-scoring/rescore-preview" -u "CLIENT_ID:CLIENT_SECRET"

Compare the three previews to ensure all scoring dimensions shift appropriately.

3. Schedule Rescoring During Low-Traffic Periods

Use executionTimeEstimate to plan rescoring during off-hours:

curl -X POST "https://api.kenbun.io/api/v1/ou/org-123/scoring/rescore-preview" \
  -u "CLIENT_ID:CLIENT_SECRET"

# Response: "executionTimeEstimate": "~15 minutes"
# Schedule rescore for 2 AM when traffic is minimal

4. Detect Unintended Consequences

Preview reveals if rule changes have unexpected side effects:

curl -X POST ".../scoring/rescore-preview" -u "CLIENT_ID:CLIENT_SECRET"

# Unexpected response:
# {
#   "totalLeads": 1000,
#   "affectedLeads": 980,
#   "estimatedIncreases": 10,
#   "estimatedDecreases": 970,
#   "averageScoreChange": -42.5,
#   "executionTimeEstimate": "~5 minutes"
# }

# 970 leads would lose points (average -42.5) - likely a rule error!
# Review rules before proceeding.

Understanding Preview Results

Affected Leads Calculation

A lead is considered "affected" if its score would change by at least 1 point after rescoring. Leads with zero score changes are counted as estimatedUnchanged.

Average Score Change

The averageScoreChange is calculated across all leads, not just affected leads. This provides a better picture of overall impact:

• Positive average: Most leads gaining points (more engagement or better fits)
• Negative average: Most leads losing points (stricter rules or decay effects)
• Near zero average: Balanced changes across the population

Execution Time Estimate

Time estimates are based on:

• Total number of leads/accounts
• Number of active rules
• Complexity of attribute filters
• Current system load

Actual rescore time may vary by ±20% depending on real-time conditions.

Best Practices

Always Preview Major Changes

• Preview before any ruleset overhaul
• Check impact after adding/removing significant rules
• Validate changes during quarterly scoring reviews

Interpret Results Carefully

• High affectedLeads percentage (>50%) suggests major rule changes
• Large averageScoreChange (>10 points) may shift score distributions significantly
• Disproportionate increases vs. decreases may indicate rule bias

Plan for Trigger Side Effects

• Rescoring can cause milestone triggers to fire
• Preview doesn't show which triggers will activate
• Review trigger thresholds before rescoring if scores will shift significantly

Compare Before/After Distributions

• Export lead scores before rescoring
• Run rescore operation
• Export scores after and compare distributions
• Validate that changes match preview estimates

Document Preview Results

• Keep records of preview outputs for audit trails
• Note date, time, and rationale for rescoring
• Track actual vs. estimated impacts for future reference

Preview Limitations

Estimates, Not Guarantees

Preview calculations are estimates based on a sampling algorithm. Actual rescore results may differ slightly due to:

• Leads added/modified between preview and rescore
• Rules changed between preview and rescore
• Internal timing differences between the preview calculation and the actual rescore

No Trigger Impact Analysis

Preview does not predict which milestone or sequence triggers will fire after rescoring. To estimate trigger impacts:

1. Review current lead score distributions
2. Identify trigger thresholds
3. Calculate how many leads will cross thresholds based on averageScoreChange

Sampling for Large Datasets

For organizations with 10,000+ leads, the preview uses statistical sampling to estimate impact. Results are accurate to within ±3% for large datasets.

Related Operations

Proceed with Rescore

After reviewing preview results, execute the actual rescore:

# Engagement scoring
POST /api/v1/ou/{ouId}/scoring/rescore

# Profile scoring
POST /api/v1/ou/{ouId}/profile-scoring/rescore

# Account scoring
POST /api/v1/ou/{ouId}/account-scoring/rescore

Monitor Rescore Progress

Check rescore job status (if applicable):

GET /api/v1/ou/{ouId}/jobs/{job_id}