Skip to main content

Engagement Levels

Engagement levels define score ranges that categorize leads based on their behavioral engagement. Use these to bucket leads into "Cold", "Warm", "Hot", etc. for easier prioritization.

When to Use This​

  • Categorize leads by engagement: Group leads into intuitive labels (Cold, Warm, Hot)
  • Simplify lead prioritization: Sales teams work with "Hot Leads" instead of "Leads with 75+ points"
  • Trigger actions by level: Send alerts when leads move from Warm to Hot
  • Reporting and dashboards: Show lead distribution across engagement levels

GET /engagement-levels​

List all engagement levels for the active Organizational Unit.

Request​

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

Response​

Status: 200 OK

{
  "levels": [
    {
      "id": "level-123",
      "name": "Cold",
      "min_score": 0,
      "max_score": 24,
      "color": "#94a3b8",
      "order": 1
    },
    {
      "id": "level-456",
      "name": "Warm",
      "min_score": 25,
      "max_score": 49,
      "color": "#fbbf24",
      "order": 2
    },
    {
      "id": "level-789",
      "name": "Hot",
      "min_score": 50,
      "max_score": 74,
      "color": "#f97316",
      "order": 3
    },
    {
      "id": "level-abc",
      "name": "Very Hot",
      "min_score": 75,
      "max_score": null,
      "color": "#ef4444",
      "order": 4
    }
  ]
}

POST /engagement-levels​

Create a new engagement level.

Request​

curl -X POST https://your-api.example.com/engagement-levels \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Super Hot",
    "min_score": 100,
    "max_score": null,
    "color": "#dc2626",
    "order": 5
  }'

Request Body​

FieldRequiredTypeDescription
nameYesstringLevel label (e.g., "Hot", "Warm")
min_scoreYesnumberMinimum score for this level (inclusive)
max_scoreNonumberMaximum score for this level (inclusive). Use null for no upper limit.
colorNostringHex color code for UI display (default: #64748b)
orderNonumberDisplay order (lower = shown first)

Response​

Status: 201 Created

{
  "id": "level-xyz",
  "name": "Super Hot",
  "min_score": 100,
  "max_score": null,
  "color": "#dc2626",
  "order": 5,
  "created_at": "2025-01-15T11:00:00Z"
}

Common Errors​

Status CodeErrorSolution
400Score ranges overlapEnsure max_score of one level doesn't overlap min_score of another
400Invalid color formatUse hex color codes like #ef4444
409Level name existsChoose a unique name or update existing level

Example Use Case​

Scenario: Create a 4-tier engagement level system

# Cold: 0-24 points
POST /engagement-levels
{"name": "Cold", "min_score": 0, "max_score": 24, "color": "#94a3b8", "order": 1}

# Warm: 25-49 points
POST /engagement-levels
{"name": "Warm", "min_score": 25, "max_score": 49, "color": "#fbbf24", "order": 2}

# Hot: 50-74 points
POST /engagement-levels
{"name": "Hot", "min_score": 50, "max_score": 74, "color": "#f97316", "order": 3}

# Very Hot: 75+ points
POST /engagement-levels
{"name": "Very Hot", "min_score": 75, "max_score": null, "color": "#ef4444", "order": 4}

Result: Leads are automatically categorized:

  • Lead with 20 points = "Cold"
  • Lead with 35 points = "Warm"
  • Lead with 65 points = "Hot"
  • Lead with 90 points = "Very Hot"

Important Notes​

Score Range Rules​

  • Ranges must not overlap
  • max_score can be null to indicate "no upper limit"
  • Highest level should have max_score: null
  • Lowest level should have min_score: 0

Display Order​

The order field controls how levels appear in the UI:

  • Lower numbers appear first
  • Use gaps (10, 20, 30) to allow insertions later
  • Independent of score ranges

See Also​