Lead Scoring
Lead scoring assigns a numeric score (0–100) to each lead based on configurable rules. Scores are stored and queryable.
How it works
Section titled “How it works”- Create one or more scoring rules. Each rule is an expression read against the lead.
- 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. - Trigger recalculation for a single lead or all leads.
Create a rule
Section titled “Create a rule”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").
Expression reference
Section titled “Expression reference”| 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"matchesLyon. Text supports only==,!=andin. - Except against
nil(next point), a missing value (absent ornullattribute, wrong type, empty text field, unset date) never satisfies==,<,<=,>,>=orin, even against another missing value (attr("effectif") >= 50andattr("effectif") <= 50are both false), while!=is true. In arithmetic it counts as 0. x == niltests emptiness like??: true whenxis missing, 0, false or empty text;x != nilis its opposite (attr("absent") == nilis true,attr("absent") != nilis false).- In arithmetic or as a condition, a text field counts as 1 when filled:
email * 30andemail != nil ? 30 : 0give 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.
Examples
Section titled “Examples”rating * 20(email != nil ? 30 : 0) + (phone != nil ? 30 : 0) + (website != nil ? 20 : 0)city == "Lyon" && has_tag("partenaire") && attr("effectif") >= 50 ? 20 : 0category in ["bakery", "restaurant"] ? 25 : 0attr("client") ? 0 : 15let recent = created_at >= date("2026-09-01"); recent && source == "google_maps" ? 10 : 0Recalculate
Section titled “Recalculate”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:
# Single leadcurl -X POST https://api.klozeo.com/api/v1/leads/cl_.../score \ -H "X-API-Key: sk_live_your_key"
# All leadscurl -X POST https://api.klozeo.com/api/v1/leads/score/batch \ -H "X-API-Key: sk_live_your_key"Filter by score
Section titled “Filter by score”# 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.emailScore display in dashboard
Section titled “Score display in dashboard”The dashboard uses the following thresholds to color-code lead scores:
| Score | Color |
|---|---|
| ≥ 70 | Green |
| ≥ 40 | Amber |
| < 40 | Red |