crm-lead-router

Score inbound leads 0–100 using firmographic and behavioral signals, then automatically route them to the correct HubSpot pipeline stage (Hot / Warm / Cold / Disqualified).

Built with Python + HubSpot Contacts API. Designed as a lightweight, portable scoring engine that works with a CSV export or live HubSpot data.

---

What it does

1. Reads leads from a CSV file or fetches live contacts from the HubSpot CRM API
2. Scores each lead 0–100 using a weighted model (see table below)
3. Maps the score to a pipeline stage
4. Optionally pushes lead_score and pipeline_stage back to HubSpot contact properties
5. Outputs a routing_report.csv with full score breakdown

---

Scoring Model

Signal	Max Points	Logic
Company size (employees)	25	500+ = 25, 200–499 = 20, 50–199 = 15, 10–49 = 8, 1–9 = 3
Industry match (ICP list)	20	Full ICP match = 20, Partial match = 10, No match = 0
Job title seniority	20	C-suite/Founder = 20, VP = 15, Director/Head = 10, Manager/Lead = 5
Has phone number	5	Present = 5, Missing = 0
Has LinkedIn URL	5	Present = 5, Missing = 0
Country/region match	10	ICP country = 10, Partial = 5, No match = 0
Recent HubSpot activity	15	< 7 days = 15, 7–30 days = 7, > 30 days = 0
Total	100

Pipeline Stage Mapping

Score Range	Stage
76 – 100	🔥 Hot
51 – 75	♨️ Warm
31 – 50	❄️ Cold
0 – 30	✗ Disqualified

---

Setup

1. Clone and install dependencies

git clone https://github.com/stevenkaranja/crm-lead-router.git
cd crm-lead-router
pip install -r requirements.txt

2. Configure environment

cp .env.example .env
# Edit .env and add your HubSpot Private App token

To create a HubSpot Private App token: HubSpot → Settings → Integrations → Private Apps → Create. Required scopes: crm.objects.contacts.read, crm.objects.contacts.write.

3. (Optional) Customize ICP config

Edit config.py to update:

• ICP_INDUSTRIES — your target industries
• ICP_COUNTRIES — your target countries/regions
• SENIORITY_MAP — title keywords and their point values

---

Usage

Score leads from a CSV file

python lead_router.py --source csv --csv-file sample_leads.csv

Score leads fetched live from HubSpot

python lead_router.py --source hubspot --limit 200

Score from HubSpot AND push scores back to contacts

python lead_router.py --source hubspot --update-hubspot

Specify a custom output report path

python lead_router.py --source csv --csv-file leads.csv --output my_report.csv

All options

usage: lead_router.py [-h] [--source {csv,hubspot}] [--csv-file CSV_FILE]
                      [--output OUTPUT] [--update-hubspot] [--limit LIMIT]

  --source        Lead source: 'csv' (default) or 'hubspot'
  --csv-file      Path to input CSV (default: sample_leads.csv)
  --output        Output report path (default: routing_report.csv)
  --update-hubspot  Push lead_score + pipeline_stage to HubSpot contacts
  --limit         Max contacts to fetch from HubSpot (default: 100)

---

CSV Input Format

Required columns for --source csv:

first_name, last_name, email, company, job_title, industry,
employee_count, country, phone, linkedin_url

See sample_leads.csv for a 10-row example with realistic African and global B2B leads.

---

Sample Output

Terminal summary

=============================================
  LEAD ROUTING SUMMARY — 10 leads processed
=============================================
  Hot             3  ( 30.0%)  ██████
  Warm            4  ( 40.0%)  ████████
  Cold            2  ( 20.0%)  ████
  Disqualified    1  ( 10.0%)  ██
=============================================

routing_report.csv columns

Column	Description
lead_score	Total score 0–100
pipeline_stage	Hot / Warm / Cold / Disqualified
score_company_size	Points from employee count
score_industry	Points from industry ICP match
score_job_title	Points from seniority
score_phone	Points for phone presence
score_linkedin	Points for LinkedIn presence
score_country	Points from country ICP match
score_recent_activity	Points from HubSpot activity recency

---

HubSpot Custom Properties

When using --update-hubspot, ensure these custom contact properties exist in your HubSpot portal:

Property Name	Type	Description
lead_score	Number	Computed 0–100 score
pipeline_stage	Single-line text	Hot / Warm / Cold / Disqualified

Create them via: HubSpot → Settings → Properties → Create property.

---

Project Structure

crm-lead-router/
├── lead_router.py       # Main scoring + routing script
├── config.py            # ICP config: industries, countries, seniority map
├── sample_leads.csv     # 10 sample leads for testing
├── requirements.txt     # Python dependencies
├── .env.example         # Environment variable template
└── README.md

---

Stack

• Python 3.10+
• pandas — CSV I/O and data manipulation
• requests — HubSpot REST API calls
• python-dotenv — Environment variable management