Scoring rules
What this page is — the rules that award points to a lead, and the action that applies them.
What it is for — ranking leads automatically, so the most promising ones are obvious without anyone reading every record.
The problem it solves — in principle, prioritisation. In practice, this is the page where two things to know before you start: scoring applies from the moment a rule is saved, and Recalculate is how you apply a new rule to leads that already exist. Section 1.
Route: /org/marketing/leads/settings?tab=rules&rule=scoring
Permission enforced by the API: Edit Existing Leads — not manage_scoring
1. Before anything else: two things that surprise everyone
A lead is scored when it is created and again when it is changed, so a new lead arrives with a score already on it.
Recalculate exists for the other case: you have just added or changed a rule and want it applied to leads that already exist. New rules do not reach old leads on their own.
It rewrites the grade only on leads whose grade is still the automatic one. A grade you chose yourself is treated as deliberate and is preserved.
It is still worth checking that your rules produce sensible scores on a handful of leads before running a recalculate across a whole project.
2. What a rule is
| Part | Meaning |
|---|---|
| Name | For humans |
| Points | Added to the score when the rule matches |
| Match type | and — every condition must match · or — any one |
| Conditions | A list of field / operator / value triples |
| Priority | Evaluation order. Does not affect the total, since all matches sum |
| Active | Inactive rules are skipped |
Operators
equals · contains · neq · starts_with · ends_with · in · gt · lt · gte · lte
in accepts a comma-separated list. Numeric comparison is used when both sides parse as numbers,
otherwise the comparison is case-insensitive text.
What a condition can test
| Kind | Examples |
|---|---|
| Native lead fields, by their JSON name | deal_value, city, country, job_title, source_id, submission_count |
| Custom field keys | industry, company_size, is_decision_maker, purchase_timeline |
| A special case | status_category — resolves to the lead's status category id |
3. The validation gap
Field names are checked when you save. A condition naming something that is not a lead field or one of your custom field keys is rejected, rather than silently never matching, and an empty value is refused for the operators where it would be meaningless.
Test Scoring is still the quickest way to confirm a rule does what you meant against a real lead.
How to tell whether a rule works
- Note the exact field key from custom fields, or the JSON field name for a native field.
- Save the rule and use Test Scoring against a lead you know should match.
- Run Recalculate, then check the score breakdown on that lead — it lists which rules fired and for how many points.
A rule absent from this list did not fire. That is the fastest way to find a condition naming a field that does not resolve.
4. Permissions — not the ones you would expect
Creating, changing and removing scoring rules, and running Test Scoring or Recalculate, all need Manage Lead Scoring Rules.
Scoring rules decide how every lead is prioritised, and Recalculate touches every lead in the project. Grant it to the people who own qualification, not to everyone who works leads.
5. Worked example
To score an enterprise lead who can sign:
| Rule | Condition | Points |
|---|---|---|
| Decision maker identified | is_decision_maker equals true | 30 |
| Deal value above 50,000 | deal_value gt 50000 | 25 |
| Buying within one month | purchase_timeline contains Immediate | 20 |
| Enterprise headcount | company_size equals 501-1000 or 1000+ | 15 |
| Referred | source_id equals a referral source id | 10 |
A lead matching all five scores 100 and grades A. One matching only the deal-value rule scores 25 and
grades D.
6. The admin contract
| Needs | Or |
|---|---|
| Custom field definitions | Conditions on them cannot resolve |
| Grades configured | Recalculate falls back to the built-in default bands |
custom_fields stored as objects | Custom-field conditions never match |
| Somebody to run Recalculate | Every score stays 0 |
7. Downstream
| The score reaches | As |
|---|---|
| The lead record | The score dial, and the computed grade chip |
| The leads list | The number in the Lifecycle Stage column, and the Lead Grade column |
| Assignment rules | A testable field |
| Quality report | The segmentation axis |
lead_grade | Overwritten on every recalculate |
8. Don't confuse this with…
| This | Not this |
|---|---|
| A scoring rule | An assignment rule — same condition shape, different effect |
manage_scoring | Edit Existing Leads, which is enforced |
| The score | The grade |
| Test Scoring | Recalculate, which writes to every lead |
9. Troubleshooting
| Symptom | Cause |
|---|---|
| Every lead scores 0 | Recalculate has never run. Section 1 |
| Still 0 after Recalculate | Conditions name fields that do not resolve. Section 3 |
| Custom-field conditions never match | custom_fields stored as a string. Section 6 |
All grades became D | Recalculate with non-matching rules. Section 1 |
| A rule looks right and fires on nothing | Check the field key exactly. Section 3 |
| Someone changed the rules who should not have | They hold the rule-management permission. Section 4 |