Skip to main content

Engagement Rules

Engagement rules assign points based on behavioral actions (email opens, page views, form submissions, etc.). These rules define how lead engagement scores are calculated.

GET /engagement-scoring/rules​

List all engagement rules across all rulesets for the active Organizational Unit.

Request​

curl -u "CLIENT_ID:CLIENT_SECRET" \
  "https://your-api.example.com/engagement-scoring/rules"

Response​

Status: 200 OK

{
  "rules": [
    {
      "id": "rule-123",
      "ruleset_id": "ruleset-abc",
      "event_type": "Email Open",
      "weight": 5,
      "active": true
    },
    {
      "id": "rule-456",
      "ruleset_id": "ruleset-abc",
      "event_type": "Page View",
      "weight": 10,
      "active": true
    }
  ]
}

POST /engagement-scoring/rules​

Create a new engagement rule within a ruleset.

Request​

curl -X POST https://your-api.example.com/engagement-scoring/rules \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "ruleset_id": "ruleset-abc",
    "event_type": "Demo Request",
    "weight": 50,
    "half_life_days": 90
  }'

Request Body​

FieldRequiredTypeDescription
ruleset_idYesstringThe ruleset to add this rule to
event_typeYesstringThe event type to score (e.g., Email Open, Page View)
weightYesnumberPoints to award when this event occurs (can be negative)
activeNobooleanWhether rule is active (default: true)
half_life_daysNointeger or nullDecay half-life in days. Each event's contribution halves every N days. Range 1 to 730. Omit or set to null to disable decay for this rule. See the Half-Life Decay guide.

Response​

Status: 201 Created

{
  "id": "rule-789",
  "ruleset_id": "ruleset-abc",
  "event_type": "demo_request",
  "weight": 50,
  "half_life_days": 90,
  "active": true,
  "created_at": "2025-01-15T11:30:00Z"
}

Example: Build a Scoring Model​

# 1. Create ruleset
POST /engagement-scoring/rulesets
{"name": "Standard Engagement", "score_type": "engagement"}

# 2. Add rules for different event types
POST /engagement-scoring/rules
{"ruleset_id": "ruleset-abc", "event_type": "Email Open", "weight": 5}

POST /engagement-scoring/rules
{"ruleset_id": "ruleset-abc", "event_type": "Page View", "weight": 10}

POST /engagement-scoring/rules
{"ruleset_id": "ruleset-abc", "event_type": "Form Submit", "weight": 25}

POST /engagement-scoring/rules
{"ruleset_id": "ruleset-abc", "event_type": "Demo Request", "weight": 50}

Result: Leads earn 5 points for email opens, 10 for page views, 25 for form submissions, and 50 for demo requests.

Common Errors​

Status CodeErrorSolution
400Missing ruleset_idProvide valid ruleset ID
400Missing event_typeSpecify event type to score
404Ruleset not foundVerify ruleset exists
409Duplicate ruleRule for this event_type already exists in ruleset

See Also​