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 /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/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 /rules​

Create a new engagement rule within a ruleset.

Request​

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

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)

Response​

Status: 201 Created

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

Example: Build a Scoring Model​

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

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

POST /rules
{"ruleset_id": "ruleset-abc", "event_type": "page_view", "weight": 10}

POST /rules
{"ruleset_id": "ruleset-abc", "event_type": "form_submit", "weight": 25}

POST /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​