CRM & Lead Generation

The CRM & Lead Generation module provides end-to-end tooling for capturing, scoring, nurturing, and converting leads within the platform. It is accessible at /dashboard/crm.

Overview

Capability	Details
Lead capture	Manual entry or public web form endpoint
Lead scoring	Automated rule-based score (0–100), versioned history
Pipeline management	Customisable stages per organisation
Activity tracking	Full interaction timeline per lead
Nurture automation	Inngest background jobs for follow-ups and reminders
Analytics	KPI dashboard, pipeline funnel, source attribution

---

Dashboard (/dashboard/crm)

The CRM dashboard is divided into four sections:

1. KPI Cards — Total leads, active count, pipeline value, won deals, conversion rate, and average lead score.
2. Pipeline Funnel — Visual bar chart showing lead count and aggregate deal value at each pipeline stage.
3. Lead Table — Filterable and paginated list of all leads with inline status updates.
4. Source Attribution — Breakdown of leads by acquisition source.

Click Add Lead from the dashboard to open the lead creation modal.

---

Pipeline Stages

Pipeline stages are configured per organisation. Each stage has:

Field	Description
name	Display name
probability	Win probability % for pipeline value calculations
colour	Hex colour for UI display
autoNurture	If true, triggers automated nurture emails when a lead enters this stage
slaDays	Expected SLA in days before escalation

Stage management requires the admin role.

---

Lead Lifecycle

Statuses

A lead progresses through the following statuses:

new → contacted → qualified → proposal → negotiating → won / lost / disqualified

Creating a Lead

Leads can be created two ways:

Via the dashboard UI — Use the "Add Lead" modal. Required fields are first name, last name, and email.

Via the public capture endpoint — Use crm.leads.capture (no authentication required). This is intended for embedding in external website forms. The endpoint validates the target organisation before inserting.

POST /api/trpc/crm.leads.capture
Content-Type: application/json

{
  "orgId": "<your-org-id>",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane@example.com",
  "source": "website"
}

Moving a Lead Through the Pipeline

Use crm.leads.moveStage to move a lead to a new pipeline stage. This automatically logs a stage-change activity on the lead's timeline.

Logging Activities

Any interaction with a lead can be recorded using crm.leads.logActivity. Supported activity types include: call, email, meeting, note, and others.

---

Lead Scoring

Every lead is automatically scored on a 0–100 scale when created and re-scored daily.

Scoring Factors

Factor	Description
Lead source quality	Some acquisition channels are weighted higher
Company size	Larger organisations score higher
Estimated deal value	Higher deal value increases the score
Decision-maker title	Title signals (e.g. "VP", "Director") boost score
Profile completeness	More complete contact data yields a higher score

Score Bands

Score	Interpretation
70–100	High quality — prioritise for outreach
40–69	Medium quality — nurture and qualify
0–39	Low quality — monitor or disqualify

Every score calculation is stored as an immutable record in lead_scores, giving a full version history.

---

Automated Background Jobs

Four Inngest functions run in the background to automate lead nurturing and reminders.

leadNurtureFollowUp

• Trigger: Event-driven — fires when a lead enters a pipeline stage where autoNurture = true
• Action: Sends a templated email and an in-app notification to the assigned sales rep

leadFollowUpReminder

• Trigger: Daily cron at 08:00 UTC
• Action: Finds all leads with overdue follow-up dates and sends in-app and email reminders to assigned reps

leadScoreRefresh

• Trigger: Daily cron at 03:00 UTC
• Action: Re-scores all open leads and records any score changes in lead_scores

leadNurtureOrgFollowUps

• Trigger: Event-driven
• Action: Fan-out handler for large multi-org deployments — dispatches per-org nurture jobs in parallel

---

API Reference

crm.leads.list

Returns a paginated, filterable list of leads.

Access: orgProcedure (authenticated org member)

Input filters:

• status — filter by lead status
• source — filter by acquisition source
• stageId — filter by pipeline stage
• dateFrom / dateTo — filter by creation date range
• page / limit — pagination

---

crm.leads.pipelineSummary

Returns aggregate statistics for the organisation's pipeline.

Access: orgProcedure

Response fields:

• total — total lead count
• active — active (non-terminal) lead count
• won / lost — closed deal counts
• totalPipelineValue — sum of estimated deal values in pence/cents
• conversionRate — percentage of leads marked won
• avgScore — average lead score across all leads
• byStage — array of { stageId, stageName, count, value } objects

---

crm.leads.capture (Public)

Public endpoint for external lead capture. Does not require authentication.

Validation: Confirms the provided orgId maps to a real, active organisation before inserting.

---

Permissions

Action	Required Role
View leads	Org member
Create / update leads	Org member
Move lead stage	Org member
Log activity	Org member
Delete lead (soft)	Admin
Manage pipeline stages	Admin
Public lead capture	No authentication

All state-changing operations are written to the platform audit log.

---

Lead Sources

The following source values are supported:

website, referral, paid_ads, organic_search, social_media, cold_outreach, event, partner, other