Lead routing rules

Lead routing rules

Routing logic usually lives in a CRM workflow nobody can read. This kit keeps it in one small JSON file with tests, so you can see every rule, prove it works on sample leads, and route a list the same way every time.

When to use

• Designing or changing routing (new segment, new rep, new region).
• Routing a one-off list (event, webinar, purchased list) before import.
• Debugging: "why did this lead go to X?" Run the lead through the rules and read the rule_id and reason.
• Not for scoring leads, and not for writing into the CRM. Import the routed CSV yourself, or rebuild the tested rules in your CRM's workflow tool.

Inputs

• Rules at data/routing-rules.json (start from the kit's examples/routing-rules.json).
• Leads CSV at data/leads.csv. Any columns; rules refer to them by name, lowercased with spaces as underscores (Lead Source becomes lead_source).
• Accounts CSV (optional) with a domain or website column and an owner column, for existing-account matching.

Rules file

• rules: checked in order, the first match wins. Each has id, when (all must match) and or when_any (one must match), assign (owner, pool, or queue), and a reason.
• Ops: ==, !=, in, not_in, >, >=, <, <=, contains, starts_with, ends_with, exists, missing. Text compares ignore case. Numbers use the first number in the cell, so 201-500 employees counts as 201.
• Built-in fields: email_domain, is_free_email (common personal email providers), company_domain.
• pools: round robin groups with optional weights ("Rep C": 2 gets twice the leads). out_of_office: people to skip.
• Existing accounts are checked before all rules when --accounts is given (skip with "account_match": false). Personal emails never match an account.
• fallback: where unmatched leads go. Default queue unassigned.
• tests: sample leads with expect_rule and optional expect_to (owner, pool name, or queue).

Steps

1. Design. Ask for the routing policy in plain words, then write the rules file. Put specific rules (junk, existing accounts, partners) before broad ones (segments). Write one test per rule plus edge cases (missing size, personal email, employee ranges).

2. Test.

   node scripts/route.mjs data/routing-rules.json --check

   Every test must pass. If one fails, show expected vs actual and fix the rule, not the test, unless the user agrees the test was wrong.

3. Route.

   node scripts/route.mjs data/routing-rules.json data/leads.csv --accounts data/accounts.csv --state data/rr-state.json --out out --name routed

   Routing refuses to run while any rule test fails. --state keeps the round robin position between runs so the next list continues where this one stopped.

4. Report from out/routed-summary.json: leads per rule, per person, how many hit the fallback, and unused_rules. A rule nobody hit may be dead or ordered too late.

Output to the user

Routed 10 leads. 5/5 rule tests pass.

| Rule | Leads |
| --- | ---: |
| existing-account | 2 |
| enterprise | 2 |
| smb | 2 |
| fallback | 1 |

Per person: Rep A 2, Rep F 2, Rep B 1, Rep C 1, Rep E 1, Partner Manager 1.
1 lead hit the fallback (UnknownCo: no employee count). Unused rule: spam-or-test.
File to import: out/routed.csv (adds routed_to, route_type, rule_id, reason).

Guardrails

• Never import or assign in the CRM. The user imports out/routed.csv.
• Keep a test for every rule you add. Do not delete a failing test to make routing run.
• Do not route on protected or sensitive attributes (age, gender, ethnicity, religion, and similar), even if a column exists.
• Lead data is personal data. Summarize in chat; do not paste the CSV.

Lead routing rules

Keeps your lead routing in one readable rules file, with tests that prove each rule works, and routes any leads CSV the same way every time. Weighted round robin, out-of-office skips, existing-account matching, and a fallback queue are built in.

Who it is for

RevOps and marketing ops teams designing or debugging routing, and anyone routing a list from an event before importing it into HubSpot, Salesforce, or another CRM.

Example

Input: examples/routing-rules.json (junk filter, personal email to nurture, partner leads, enterprise, mid-market, and SMB pools, one rep out of office), examples/leads.csv (10 leads), and examples/accounts.csv.

Output: out/routed.csv with four new columns, for example:

buyer@northwind.example,...,Rep A,owner,existing-account,existing account northwind.example
cto@fabrikam.example,...,Rep A,pool,enterprise,"1,000+ employees"
someone@gmail.com,...,nurture,queue,free-email-students,Personal email and no company size
new@unknownco.example,...,routing-review,queue,fallback,no rule matched

And out/routed-summary.json: counts per rule and per person, rules nobody hit, and test results (5/5 pass).

What it can access

• Runs node scripts/route.mjs (Node built-ins only, no network).
• Reads data/ (plus the kit's own examples/), writes data/ (round robin state) and out/.

Setup

None. Copy examples/routing-rules.json to data/ and edit it, or ask Claude to write it from your routing policy.