Skip to main content

Profile Levels

Profile levels define score ranges that categorize leads based on their demographic/firmographic fit. Use these to bucket leads into "Poor Fit", "Good Fit", "Excellent Fit", etc. based on ICP matching.

When to Use This​

  • Categorize leads by ICP fit: Group leads into fit categories independent of behavioral engagement
  • Multi-dimensional qualification: Combine profile fit levels with engagement levels for complete lead scoring
  • Target messaging by fit: Send different messages to "Excellent Fit" vs "Poor Fit" prospects
  • Sales prioritization: Focus on high engagement + high fit leads first

GET /profile-levels​

List all profile levels for the active Organizational Unit.

Request​

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

Response​

Status: 200 OK

{
  "levels": [
    {
      "id": "level-123",
      "name": "Poor Fit",
      "min_score": 0,
      "max_score": 29,
      "color": "#94a3b8",
      "order": 1
    },
    {
      "id": "level-456",
      "name": "Good Fit",
      "min_score": 30,
      "max_score": 69,
      "color": "#fbbf24",
      "order": 2
    },
    {
      "id": "level-789",
      "name": "Excellent Fit",
      "min_score": 70,
      "max_score": null,
      "color": "#22c55e",
      "order": 3
    }
  ]
}

POST /profile-levels​

Create a new profile level.

Request​

curl -X POST https://your-api.example.com/profile-levels \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Perfect Fit",
    "min_score": 90,
    "max_score": null,
    "color": "#16a34a",
    "order": 4
  }'

Request Body​

FieldRequiredTypeDescription
nameYesstringLevel label (e.g., "Good Fit", "Poor Fit")
min_scoreYesnumberMinimum profile score for this level (inclusive)
max_scoreNonumberMaximum profile 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": "Perfect Fit",
  "min_score": 90,
  "max_score": null,
  "color": "#16a34a",
  "order": 4,
  "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 #22c55e
409Level name existsChoose a unique name or update existing level

Example Use Case​

Scenario: Create a 3-tier profile fit system based on ICP matching

# Poor Fit: 0-29 points (small companies, wrong industry)
POST /profile-levels
{"name": "Poor Fit", "min_score": 0, "max_score": 29, "color": "#94a3b8", "order": 1}

# Good Fit: 30-69 points (medium companies, adjacent industries)
POST /profile-levels
{"name": "Good Fit", "min_score": 30, "max_score": 69, "color": "#fbbf24", "order": 2}

# Excellent Fit: 70+ points (enterprise companies, target industry, C-level)
POST /profile-levels
{"name": "Excellent Fit", "min_score": 70, "max_score": null, "color": "#22c55e", "order": 3}

Result: Leads are automatically categorized by ICP match:

  • Small retail company contact = "Poor Fit" (15 points)
  • Mid-size tech company manager = "Good Fit" (45 points)
  • Enterprise tech company VP = "Excellent Fit" (85 points)

Multi-Dimensional Scoring Example​

Combine engagement levels with profile levels for complete qualification:

EngagementProfile FitAction
Hot (75+)Excellent Fit (70+)Top Priority - Immediate outreach
Hot (75+)Good Fit (30-69)High Priority - Personalized outreach
Hot (75+)Poor Fit (0-29)Medium Priority - Nurture or disqualify
Warm (25-49)Excellent Fit (70+)High Priority - Warm up for conversion
Cold (0-24)Excellent Fit (70+)Medium Priority - Nurture with targeted content
Cold (0-24)Poor Fit (0-29)Low Priority - Exclude from outreach

Important Notes​

Profile Scoring Required​

Profile levels require active profile scoring rules. Set up:

  1. Profile mappings: Map event metadata to profile fields
POST /profile-mappings
{"metadata_key": "company_size", "profile_field": "company_employee_count"}
  1. Profile ruleset: Create ruleset for ICP scoring
POST /profile-scoring/rulesets
{"name": "ICP Fit Score"}
  1. Profile rules: Define scoring logic
POST /profile-scoring/rulesets/{id}/rules
{"profile_field": "company_employee_count", "value": "501+", "weight": 50}
  1. Profile levels: Categorize scores into fit levels (this endpoint)

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

See Also​