Skip to content

Lead Scoring

Lead scoring assigns a numeric score (0–100) to each lead based on configurable rules. Scores are stored and queryable.

  1. Create one or more scoring rules. Each rule is an expression read against the lead.
  2. Each rule produces a value; all rule values are added and the total is clamped to 0–100. Without any rule, the score is rating * 20.
  3. Trigger recalculation for a single lead or all leads.
Terminal window
curl -X POST https://api.klozeo.com/api/v1/scoring-rules \
-H "X-API-Key: sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Partner in Lyon",
"expression": "city == \"Lyon\" && has_tag(\"partenaire\") && attr(\"effectif\") >= 50 ? 20 : 0",
"priority": 1
}'

A rule naming an unknown field or function is refused with 400 invalid_scoring_expression and a message that says what is wrong and where, for example unknown field "effectif" … custom attributes: attr("effectif").

What Syntax Example
Number fields rating (0 when absent), review_count, tags (number of tags) rating * 20
Text fields email, phone, website, city, country, category, source, status city == "Lyon"
Company identifier siren: the normalized 9-digit SIREN, missing when unset (a SIRET is stored as its SIREN) siren != nil ? 10 : 0
Date fields created_at, last_interaction_at created_at >= date("2026-01-01")
Tag has_tag("name"), case-insensitive has_tag("vip") ? 15 : 0
Custom attribute attr("name"), typed by the attribute: number, text, bool or date attr("effectif") >= 50
Date literal date("YYYY-MM-DD") or RFC 3339; date(attr("x")) reads a date stored as text date(attr("signed_on")) < date("2026-07-01")
Arithmetic +, -, *, / (division by zero gives 0) rating * 10 + tags
Comparison ==, !=, <, <=, >, >= review_count > 100
List membership value in ["a", "b"] status in ["qualified", "demo"]
Logic &&, ||, ! !has_tag("lost")
Ternary condition ? if_true : if_false rating > 4 ? 30 : 0
Fallback a ?? b: b when a is empty, zero, false or missing attr("budget") ?? 0
Variables let name = value; before the final value let q = rating * 15; q + tags
Math min, max, abs, floor, ceil, round min(review_count, 200) / 4
  • Text comparisons ignore case: city == "lyon" matches Lyon. Text supports only ==, != and in.
  • Except against nil (next point), a missing value (absent or null attribute, wrong type, empty text field, unset date) never satisfies ==, <, <=, >, >= or in, even against another missing value (attr("effectif") >= 50 and attr("effectif") <= 50 are both false), while != is true. In arithmetic it counts as 0.
  • x == nil tests emptiness like ??: true when x is missing, 0, false or empty text; x != nil is its opposite (attr("absent") == nil is true, attr("absent") != nil is false).
  • In arithmetic or as a condition, a text field counts as 1 when filled: email * 30 and email != nil ? 30 : 0 give the same result.
  • Expressions are limited to 1,000 bytes and 64 nesting levels.

A rule saved before this validation existed is validated again when you edit its expression; until then, if it no longer compiles, it adds nothing to the score. See the API reference for details.

rating * 20
(email != nil ? 30 : 0) + (phone != nil ? 30 : 0) + (website != nil ? 20 : 0)
city == "Lyon" && has_tag("partenaire") && attr("effectif") >= 50 ? 20 : 0
category in ["bakery", "restaurant"] ? 25 : 0
attr("client") ? 0 : 15
let recent = created_at >= date("2026-09-01"); recent && source == "google_maps" ? 10 : 0

Once the account has at least one rule, a lead’s score is recalculated automatically, before the API responds, when the lead is created, merged into (duplicate on create or batch), updated (REST or MCP), enriched with company data, or when one of its custom attributes changes. An account can have up to 100 rules.

After you create, delete, or change the expression of a rule, all the account’s leads are recalculated in the background: seconds for a small account, a few minutes for a very large one. Meanwhile scores mix old and new rules; each batch of changed scores sends a leads.scored webhook. Deleting the last rule leaves scores unchanged.

Explicit recalculation remains available:

Terminal window
# Single lead
curl -X POST https://api.klozeo.com/api/v1/leads/cl_.../score \
-H "X-API-Key: sk_live_your_key"
# All leads
curl -X POST https://api.klozeo.com/api/v1/leads/score/batch \
-H "X-API-Key: sk_live_your_key"
Terminal window
# Leads with score >= 70
?filter=and.gte.score.70
# High-value leads (score >= 80, has email)
?filter=and.gte.score.80&filter=and.is_not_empty.email

The dashboard uses the following thresholds to color-code lead scores:

Score Color
≥ 70 Green
≥ 40 Amber
< 40 Red