Recommendations API

The recommendations router generates context-aware next-best-action recommendations for scored entities. Combines system rules (tier-based, signal-based) with admin-defined custom rules. Supports one-click action execution.

Router namespace: recommendations

Source: src/server/trpc/routers/recommendations.ts

Procedures

Procedure	Type	Access	Description
getForEntity	query	tenant	Context-aware recommendations for an entity
listRules	query	admin	All system and custom recommendation rules
upsertRule	mutation	admin	Create or update a custom rule
deleteRule	mutation	admin	Delete a custom rule (system rules protected)
executeAction	mutation	tenant	Execute a one-click recommendation action

---

getForEntity

Returns prioritized recommendations for a specific entity based on its current scores, tier, engagement signals, and buying group status.

recommendations.getForEntity.queryOptions(input)

Input

Field	Type	Required	Description
entityId	string	Yes	Entity identifier
entityType	"person" | "account" | "opportunity"	Yes	Entity type

Response

[
  {
    "id": "rec_001",
    "priority": 1,
    "type": "engagement",
    "title": "Schedule executive meeting",
    "description": "Account is hot-tier with cooling champion engagement. Re-engage the decision maker.",
    "action": "assign_to_rep",
    "actionPayload": { "repId": "rep_123", "accountId": "acc_456" },
    "ruleId": "rule_sys_hot_cooling",
    "confidence": 0.88
  },
  {
    "id": "rec_002",
    "priority": 2,
    "type": "buying_group",
    "title": "Fill missing technical evaluator role",
    "description": "Buying group is 75% complete. 2 candidates identified for technical evaluator.",
    "action": "add_to_crm",
    "actionPayload": { "email": "tech.lead@example.com", "role": "technical_evaluator" },
    "ruleId": "rule_sys_missing_role",
    "confidence": 0.75
  }
]

Example

const trpc = useTRPC();
const { data } = useQuery(
  trpc.recommendations.getForEntity.queryOptions({
    entityId: "acc_456",
    entityType: "account",
  })
);

---

listRules

Returns all recommendation rules including built-in system rules and admin-created custom rules.

recommendations.listRules.queryOptions()

Access: Admin only

Input

None.

Response

[
  {
    "id": "rule_sys_hot_cooling",
    "name": "Hot account with cooling engagement",
    "isSystem": true,
    "conditions": {
      "tier": "hot",
      "engagementVelocity": "decreasing"
    },
    "action": "assign_to_rep",
    "priority": 1,
    "enabled": true
  },
  {
    "id": "rule_custom_001",
    "name": "High-fit cold account outreach",
    "isSystem": false,
    "conditions": {
      "tier": "cold",
      "fitScore": { "min": 70 }
    },
    "action": "add_to_sequence",
    "priority": 5,
    "enabled": true
  }
]

---

upsertRule

Creates a new custom rule or updates an existing one. System rules cannot be modified through this procedure.

recommendations.upsertRule.mutationOptions(options)

Access: Admin only

Input

Field	Type	Required	Description
rule	object	Yes	Rule definition
rule.id	string	No	Rule ID (omit to create new)
rule.name	string	Yes	Human-readable rule name
rule.conditions	object	Yes	Trigger conditions (tier, score thresholds, signals)
rule.action	string	Yes	Action type to recommend
rule.priority	number	No	Priority (lower = higher priority)
rule.enabled	boolean	No	Whether the rule is active

Response

{
  "id": "rule_custom_001",
  "success": true
}

---

deleteRule

Deletes a custom recommendation rule. System rules are protected and cannot be deleted.

recommendations.deleteRule.mutationOptions(options)

Access: Admin only

Input

Field	Type	Required	Description
ruleId	string	Yes	Rule identifier

Response

{ "success": true }

warning

Attempting to delete a system rule throws a FORBIDDEN error. System rules can only be disabled, not deleted.

---

executeAction

Executes a one-click action from a recommendation. Actions are dispatched to the appropriate integration (Salesforce, Customer.io, internal assignment).

recommendations.executeAction.mutationOptions(options)

Input

Field	Type	Required	Description
action	string	Yes	Action type (see table below)
payload	object	Yes	Action-specific parameters

Supported Actions

Action	Description
add_to_crm	Create or update a CRM record
assign_to_rep	Assign entity to a sales rep
add_to_sequence	Add contact to a nurture sequence
create_task	Create a CRM task for follow-up
send_alert	Send a Slack notification
update_segment	Update Customer.io segment membership

Response

{
  "executed": true,
  "action": "assign_to_rep",
  "result": {
    "assignedTo": "rep_123",
    "entityId": "acc_456"
  }
}

Example

const trpc = useTRPC();

const mutation = useMutation(
  trpc.recommendations.executeAction.mutationOptions({
    onSuccess: () => {
      queryClient.invalidateQueries({
        queryKey: trpc.recommendations.getForEntity.queryKey(),
      });
    },
  })
);

mutation.mutate({
  action: "assign_to_rep",
  payload: { repId: "rep_123", accountId: "acc_456" },
});

Related Pages

• Scoring API -- Scoring data that drives recommendations
• Activation API -- Automated activation of score-based actions
• Buying Groups API -- Buying group context for recommendations