Skip to main content

Engagement Rulesets

Engagement rulesets are containers that group related engagement scoring rules together. Each ruleset tracks a separate engagement score, allowing you to test different scoring models or track different engagement types simultaneously.

When to Use This​

  • Organize scoring logic: Group related rules (e.g., "Email Engagement", "Product Trial Activity")
  • Test scoring models: Run multiple rulesets side-by-side to compare effectiveness
  • Campaign-specific scoring: Create temporary rulesets for specific campaigns or time periods
  • Multi-dimensional scoring: Track different aspects of engagement separately

GET /rulesets​

List all engagement rulesets for the active Organizational Unit.

Request​

curl -u "CLIENT_ID:CLIENT_SECRET" \
  "https://your-api.example.com/rulesets"

Response​

Status: 200 OK

{
  "rulesets": [
    {
      "id": "ruleset-abc",
      "name": "Standard Engagement",
      "score_field": "engagement_score",
      "active": true,
      "start_date": null,
      "end_date": null,
      "created_at": "2025-01-15T10:00:00Z"
    },
    {
      "id": "ruleset-xyz",
      "name": "Q1 Campaign",
      "score_field": "campaign_score",
      "active": true,
      "start_date": "2025-01-01",
      "end_date": "2025-03-31",
      "created_at": "2025-01-15T11:00:00Z"
    }
  ]
}

POST /rulesets​

Create a new engagement ruleset.

Request​

curl -X POST https://your-api.example.com/rulesets \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Trial Engagement",
    "score_field": "trial_score",
    "active": true
  }'

Request Body​

FieldRequiredTypeDescription
nameYesstringRuleset name
score_fieldNostringCustom score field name (default: "engagement_score")
activeNobooleanWhether ruleset is active (default: true)
start_dateNostringISO 8601 date when ruleset becomes active
end_dateNostringISO 8601 date when ruleset expires

Response​

Status: 201 Created

{
  "id": "ruleset-new",
  "name": "Product Trial Engagement",
  "score_field": "trial_score",
  "active": true,
  "start_date": null,
  "end_date": null,
  "created_at": "2025-01-15T12:00:00Z"
}

Common Errors​

Status CodeErrorSolution
400Missing nameProvide a ruleset name
409Duplicate nameRuleset with this name already exists
400Invalid date formatUse ISO 8601 format (YYYY-MM-DD)

Example Use Cases​

Use Case 1: Campaign-Specific Scoring​

Track engagement for a specific campaign with time boundaries:

POST /rulesets
{
  "name": "Q1 Webinar Series",
  "score_field": "webinar_engagement",
  "start_date": "2025-01-01",
  "end_date": "2025-03-31"
}

# Add rules for webinar-specific events
POST /rules
{"ruleset_id": "...", "event_type": "webinar_registration", "weight": 10}

POST /rules
{"ruleset_id": "...", "event_type": "webinar_attendance", "weight": 30}

Use Case 2: A/B Test Scoring Models​

Run two scoring models simultaneously to see which better predicts conversions:

# Model A: Conservative scoring
POST /rulesets
{"name": "Scoring Model A", "score_field": "score_a"}

POST /rules
{"ruleset_id": "model-a-id", "event_type": "email_open", "weight": 3}

# Model B: Aggressive scoring
POST /rulesets
{"name": "Scoring Model B", "score_field": "score_b"}

POST /rules
{"ruleset_id": "model-b-id", "event_type": "email_open", "weight": 10}

Result: Each lead has two scores (score_a and score_b). Compare which model's high-scorers convert better.

Use Case 3: Multi-Stage Engagement​

Track engagement across different customer journey stages:

# Awareness stage
POST /rulesets
{"name": "Awareness Engagement", "score_field": "awareness_score"}

# Consideration stage
POST /rulesets
{"name": "Consideration Engagement", "score_field": "consideration_score"}

# Decision stage
POST /rulesets
{"name": "Decision Engagement", "score_field": "decision_score"}

Important Notes​

Score Fields​

Each ruleset can track scores in a custom field:

  • Default: engagement_score
  • Custom: Any field name (e.g., campaign_score, trial_score)
  • Multiple rulesets can write to the same field (scores add up) or different fields (separate tracking)

Active vs. Inactive​

  • Active: Rules in this ruleset currently award points
  • Inactive: Historical data preserved, but no new points awarded

Time Boundaries​

  • start_date: Ruleset inactive before this date
  • end_date: Ruleset inactive after this date
  • Both optional - omit for always-active rulesets

See Also​