Propensity API
The propensity router exposes the ML propensity pipeline -- cached predictions, model health, configuration, and the activation workflow that transitions from platform-only scoring to ML-augmented scoring.
Router namespace: propensity
Source: src/server/trpc/routers/propensity.ts
Procedures
| Procedure | Type | Access | Description |
|---|---|---|---|
getPredictions | query | tenant | Cached ML propensity scores for an entity type |
getModelStatus | query | admin | Full model status: AUC, features, training history, data volume |
getConfig | query | admin | Current propensity configuration |
updateConfig | mutation | admin | Update propensity configuration |
activateML | mutation | admin | Activate ML scoring (requires AUC >= 0.65) |
startPreview | mutation | admin | Start a 7-day side-by-side preview |
getEntityPropensity | query | tenant | Full propensity detail with SHAP values for one entity |
getPredictions
Returns cached ML propensity scores for a given entity type. Scores are refreshed on each scoring run.
propensity.getPredictions.queryOptions(input)
Input
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
entityType | "person" | "account" | "opportunity" | Yes | -- | Entity type to retrieve predictions for |
limit | number (1-1000) | No | 100 | Maximum predictions to return |
Response
[
{
"entityId": "acc_456",
"entityType": "account",
"propensityScore": 0.82,
"confidence": 0.91,
"predictedAt": "2026-03-05T10:30:00.000Z"
}
]
Example
const trpc = useTRPC();
const { data } = useQuery(
trpc.propensity.getPredictions.queryOptions({
entityType: "account",
limit: 50,
})
);
getModelStatus
Returns comprehensive model health information including AUC, feature importance, training history, and available data volume.
propensity.getModelStatus.queryOptions()
Access: Admin only
Input
None.
Response
{
"isActive": true,
"auc": 0.78,
"lastTrainedAt": "2026-03-04T02:00:00.000Z",
"trainingHistory": [
{ "trainedAt": "2026-03-04T02:00:00.000Z", "auc": 0.78, "samples": 1250 },
{ "trainedAt": "2026-02-25T02:00:00.000Z", "auc": 0.75, "samples": 1100 }
],
"topFeatures": [
{ "name": "engagement_score", "importance": 0.32 },
{ "name": "fit_score", "importance": 0.28 },
{ "name": "days_since_last_activity", "importance": 0.15 }
],
"dataVolume": {
"closedWon": 145,
"closedLost": 312,
"total": 457
}
}
getConfig
Returns the current propensity pipeline configuration.
propensity.getConfig.queryOptions()
Access: Admin only
Input
None.
Response
{
"minClosedWon": 50,
"retrainSchedule": "weekly",
"mlActivated": true,
"propensityWeight": 0.3
}
| Field | Description |
|---|---|
minClosedWon | Minimum closed-won deals required before ML can activate |
retrainSchedule | How often the model retrains ("daily", "weekly", "monthly") |
mlActivated | Whether ML scoring is active for this tenant |
propensityWeight | Weight of propensity score in the combined score (0-1) |
updateConfig
Updates propensity pipeline configuration.
propensity.updateConfig.mutationOptions(options)
Access: Admin only
Input
| Field | Type | Required | Description |
|---|---|---|---|
minClosedWon | number | No | Minimum closed-won threshold |
retrainSchedule | "daily" | "weekly" | "monthly" | No | Retrain frequency |
propensityWeight | number (0-1) | No | Weight in combined score |
Response
{ "success": true }
activateML
Activates ML-augmented scoring for the tenant. The model must have an AUC of at least 0.65 to activate. Use preview: true to check eligibility without activating.
propensity.activateML.mutationOptions(options)
Access: Admin only
Input
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
preview | boolean | No | false | If true, returns eligibility without activating |
Response
{
"activated": true,
"auc": 0.78,
"eligible": true,
"reason": null
}
Activation fails if the model AUC is below 0.65 or there is insufficient training data. The response includes a reason string explaining the failure.
startPreview
Starts a 7-day side-by-side preview that runs ML scoring in parallel with the platform model without affecting live scores. Use this to evaluate ML quality before activating.
propensity.startPreview.mutationOptions(options)
Access: Admin only
Input
None.
Response
{
"previewStarted": true,
"endsAt": "2026-03-12T10:30:00.000Z"
}
getEntityPropensity
Returns full propensity detail for a single entity including the propensity score, confidence, and SHAP feature explanations.
propensity.getEntityPropensity.queryOptions(input)
Input
| Field | Type | Required | Description |
|---|---|---|---|
entityId | string | Yes | Entity identifier |
Response
{
"entityId": "acc_456",
"propensityScore": 0.82,
"confidence": 0.91,
"shapValues": [
{ "feature": "engagement_score", "value": 0.15, "direction": "positive" },
{ "feature": "fit_score", "value": 0.12, "direction": "positive" },
{ "feature": "days_since_last_activity", "value": -0.08, "direction": "negative" }
],
"predictedAt": "2026-03-05T10:30:00.000Z"
}
SHAP values explain how each feature contributed to the prediction. Positive values push the score up; negative values push it down. The sum of all SHAP values equals the difference from the base rate.
Related Pages
- Scoring API -- Core scoring execution and entity data
- Dual Model API -- Platform vs customer model comparison
- Analytics API -- Score history and conversion attribution