Lead Management Guide

Overview

Leads represent potential customers who have expressed interest in your products or services. The CRM system provides comprehensive lead management capabilities including capturing, tracking, scoring, assigning, and qualifying leads through their lifecycle until they convert to customers or are disqualified.

Lead Lifecycle

Lead Status Progression

Leads progress through defined statuses that represent their qualification stage:

Status	Description	Next Possible Status
New	Freshly captured lead, not yet contacted	Contacted, Unqualified, Lost
Contacted	Initial contact made with lead	Qualified, Unqualified, Nurturing, Lost
Qualified	Lead meets qualification criteria (BANT)	Converted, Nurturing, Lost
Nurturing	Lead placed in nurture campaign	Contacted, Qualified, Lost
Unqualified	Lead doesn't meet criteria currently	Recycled, Lost
Recycled	Unqualified lead being reconsidered	Contacted, Qualified
Converted	Lead successfully converted to customer	Terminal status
Lost	Lead lost to competitor or disengaged	Terminal status
Disqualified	Lead permanently disqualified	Terminal status

Status Transitions

The system enforces valid status transitions. For example, you cannot move directly from "New" to "Converted" - leads must progress through "Contacted" and "Qualified" stages first.

Lead Sources

Track where leads originate to measure channel effectiveness:

Inbound Sources:

website - Direct website visits
webinar - Webinar registrations
content_download - Ebook/whitepaper downloads
content_marketing - Blog posts, articles
organic_search - SEO traffic
social_media - Social media engagement
direct_traffic - Direct URL entry

Outbound Sources:

cold_call - Cold calling campaigns
cold_outreach - Email/LinkedIn outreach
email_campaign - Marketing email campaigns
trade_show - Trade show booth interactions

Paid Sources:

paid_search - PPC advertising (Google Ads, etc.)
advertisement - Display ads, sponsored content

Other Sources:

referral - Customer or partner referrals
partner - Partner channel leads
other - Miscellaneous sources

Lead Scoring

Leads receive automatic scores based on behavioral and demographic factors:

Lead Score Components

Behavioral Score (0-50)

Website engagement (page views, time on site)
Content downloads
Email opens/clicks
Webinar attendance
Demo requests

Demographic Score (0-50)

Company size
Industry fit
Job title/role
Geographic location
Budget indicators

Score Interpretation

Score Range	Grade	Temperature	Action
80-100	A	Hot	Immediate contact, high priority
60-79	B	Warm	Contact within 24 hours
40-59	C	Cool	Contact within 1 week
20-39	D	Cold	Add to nurture campaign
0-19	F	Frozen	Low priority/reconsider qualification

Creating Leads

Basic Lead Creation

Endpoint: POST /api/v1/crm/leads

Authentication: Required (Bearer token)

Request Body:

json

{
  "email": "sarah.johnson@techcorp.com",
  "source": "website",
  "contact_info": {
    "first_name": "Sarah",
    "last_name": "Johnson",
    "phone": "+1-555-0123",
    "company": "TechCorp Inc",
    "address": {
      "street": "123 Innovation Drive",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "USA"
    }
  },
  "status": "new",
  "estimated_value": 50000.00,
  "probability": 25,
  "assigned_user_id": 5,
  "tags": ["enterprise", "saas"],
  "notes": "Interested in enterprise plan. Requested demo."
}

Required Fields:

email - Valid email address (must be unique)
source - Lead source (see Lead Sources section)
contact_info.first_name - First name
contact_info.last_name - Last name

Optional Fields:

contact_info.phone - Phone number
contact_info.company - Company name
contact_info.address - Full address object
status - Initial status (defaults to "new")
estimated_value - Potential deal value in dollars
probability - Win probability 0-100% (auto-calculated if not provided)
assigned_user_id - Assign to specific user
organization_id - Link to organization
campaign_id - Link to marketing campaign
tags - Array of tags for categorization
custom_fields - Custom data object
notes - Internal notes

Response (201 Created):

json

{
  "message": "Lead created successfully",
  "data": {
    "id": 1234,
    "email": "sarah.johnson@techcorp.com",
    "source": "website",
    "status": "new",
    "contact_info": {
      "first_name": "Sarah",
      "last_name": "Johnson",
      "full_name": "Sarah Johnson",
      "phone": "+1-555-0123",
      "company": "TechCorp Inc"
    },
    "lead_score": {
      "total_score": 0,
      "behavioral_score": 0,
      "demographic_score": 0,
      "grade": "F",
      "temperature": "frozen"
    },
    "estimated_value": 50000.00,
    "probability": 25,
    "assigned_user_id": 5,
    "tags": ["enterprise", "saas"],
    "created_at": "2025-12-17T10:30:00Z",
    "updated_at": "2025-12-17T10:30:00Z"
  }
}

Error Response (422 Unprocessable Entity):

json

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["This email address already exists in our system"]
  }
}

Listing and Filtering Leads

Get All Leads

Endpoint: GET /api/v1/crm/leads

Authentication: Required (Bearer token)

Query Parameters:

status (string) - Filter by status (new, contacted, qualified, etc.)
source (string) - Filter by lead source
assigned_user_id (integer) - Filter by assigned user
search (string) - Search by name, email, or company
per_page (integer) - Results per page (default: 25, max: 100)
page (integer) - Page number
sort_by (string) - Sort field (created_at, updated_at, estimated_value, lead_score)
sort_direction (string) - Sort direction (asc, desc)

Example Request:

bash

GET /api/v1/crm/leads?status=qualified&source=website&per_page=50&sort_by=estimated_value&sort_direction=desc

Response (200 OK):

json

{
  "data": [
    {
      "id": 1234,
      "email": "sarah.johnson@techcorp.com",
      "source": "website",
      "status": "qualified",
      "contact_info": {
        "first_name": "Sarah",
        "last_name": "Johnson",
        "full_name": "Sarah Johnson",
        "phone": "+1-555-0123",
        "company": "TechCorp Inc"
      },
      "lead_score": {
        "total_score": 85,
        "behavioral_score": 45,
        "demographic_score": 40,
        "grade": "A",
        "temperature": "hot"
      },
      "estimated_value": 50000.00,
      "probability": 80,
      "assigned_user_id": 5,
      "qualified_at": "2025-12-15T14:20:00Z",
      "created_at": "2025-12-10T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 127,
    "last_page": 3
  },
  "links": {
    "first": "/api/v1/crm/leads?page=1",
    "last": "/api/v1/crm/leads?page=3",
    "prev": null,
    "next": "/api/v1/crm/leads?page=2"
  }
}

Search Leads

Endpoint: GET /api/v1/crm/leads/search

Query Parameters:

q (string, required) - Search query (minimum 2 characters)
per_page (integer) - Results per page (default: 25)
page (integer) - Page number

Searches across:

Email addresses
First and last names
Company names
Phone numbers

Example Request:

bash

GET /api/v1/crm/leads/search?q=techcorp

Viewing Lead Details

Endpoint: GET /api/v1/crm/leads/{id}

Query Parameters:

includes (string, optional) - Comma-separated relationships to include: activities, opportunities, customer

Example:

bash

GET /api/v1/crm/leads/1234?includes=activities,opportunities

Response (200 OK):

json

{
  "data": {
    "id": 1234,
    "email": "sarah.johnson@techcorp.com",
    "source": "website",
    "status": "qualified",
    "contact_info": {
      "first_name": "Sarah",
      "last_name": "Johnson",
      "full_name": "Sarah Johnson",
      "phone": "+1-555-0123",
      "company": "TechCorp Inc",
      "address": {
        "street": "123 Innovation Drive",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "USA"
      }
    },
    "lead_score": {
      "total_score": 85,
      "behavioral_score": 45,
      "demographic_score": 40,
      "grade": "A",
      "temperature": "hot"
    },
    "estimated_value": 50000.00,
    "probability": 80,
    "assigned_user_id": 5,
    "assigned_user": {
      "id": 5,
      "name": "John Smith",
      "email": "john.smith@yourcompany.com"
    },
    "tags": ["enterprise", "saas", "hot-lead"],
    "notes": "Interested in enterprise plan. Demo scheduled for Dec 20.",
    "qualified_at": "2025-12-15T14:20:00Z",
    "created_at": "2025-12-10T10:30:00Z",
    "updated_at": "2025-12-16T09:15:00Z",
    "last_activity_at": "2025-12-16T09:15:00Z"
  }
}

Updating Leads

Endpoint: PUT /api/v1/crm/leads/{id} or PATCH /api/v1/crm/leads/{id}

Request Body (partial update allowed):

json

{
  "status": "qualified",
  "estimated_value": 75000.00,
  "probability": 70,
  "contact_info": {
    "phone": "+1-555-0199"
  },
  "tags": ["enterprise", "saas", "hot-lead", "demo-completed"],
  "notes": "Demo completed successfully. Positive feedback. Moving to proposal stage."
}

Response (200 OK):

json

{
  "message": "Lead updated successfully",
  "data": {
    "id": 1234,
    "status": "qualified",
    "estimated_value": 75000.00,
    "probability": 70,
    "updated_at": "2025-12-17T11:45:00Z"
  }
}

Assigning Leads

Assign Lead to User

Endpoint: POST /api/v1/crm/leads/{leadId}/assign

Request Body:

json

{
  "user_id": 7,
  "notify": true
}

Response (200 OK):

json

{
  "message": "Lead assigned successfully",
  "data": {
    "id": 1234,
    "assigned_user_id": 7,
    "assigned_user": {
      "id": 7,
      "name": "Jane Davis",
      "email": "jane.davis@yourcompany.com"
    },
    "assigned_at": "2025-12-17T12:00:00Z"
  }
}

Use Cases for Assignment:

Round-robin distribution among sales team
Territory-based assignment
Skill-based routing
Workload balancing
Re-assignment when rep leaves

Updating Lead Scores

Manual Score Update

Endpoint: PATCH /api/v1/crm/leads/{leadId}/score

Request Body:

json

{
  "behavioral_score": 45,
  "demographic_score": 40,
  "reason": "Attended product demo, high engagement"
}

Response (200 OK):

json

{
  "message": "Lead score updated successfully",
  "data": {
    "id": 1234,
    "lead_score": {
      "total_score": 85,
      "behavioral_score": 45,
      "demographic_score": 40,
      "grade": "A",
      "temperature": "hot"
    },
    "updated_at": "2025-12-17T13:30:00Z"
  }
}

When to Update Scores:

After significant engagement (demo, meeting, trial signup)
When demographic information changes (promoted, company growth)
Manual adjustment based on sales rep feedback
Integration with marketing automation platforms

Bulk Operations

Bulk Actions

Endpoint: POST /api/v1/crm/leads/bulk-actions

Request Body:

json

{
  "action": "assign",
  "lead_ids": [1234, 1235, 1236],
  "parameters": {
    "user_id": 7
  }
}

Supported Actions:

assign - Assign multiple leads to user
update_status - Change status for multiple leads
add_tags - Add tags to multiple leads
remove_tags - Remove tags from multiple leads
delete - Delete multiple leads

Example - Update Status:

json

{
  "action": "update_status",
  "lead_ids": [1234, 1235, 1236],
  "parameters": {
    "status": "nurturing"
  }
}

Response (200 OK):

json

{
  "message": "Bulk action completed successfully",
  "data": {
    "action": "assign",
    "processed": 3,
    "successful": 3,
    "failed": 0
  }
}

Deleting Leads

Endpoint: DELETE /api/v1/crm/leads/{id}

Response (200 OK):

json

{
  "message": "Lead deleted successfully"
}

Permanent Deletion

Deleting a lead is permanent and cannot be undone. Consider updating the status to "lost" or "disqualified" instead to maintain historical data.

Business Scenarios

Scenario 1: Website Lead Capture

Context: Visitor fills out "Request Demo" form on website

Workflow:

Capture lead via API with source website
System assigns default probability (25%)
Lead automatically assigned via round-robin
Sales rep receives notification
Rep contacts within 24 hours
Update status to contacted after first touch

API Calls:

bash

# 1. Create lead
POST /api/v1/crm/leads
{
  "email": "prospect@company.com",
  "source": "website",
  "contact_info": { ... },
  "custom_fields": {
    "form_page": "/request-demo",
    "interest": "Enterprise Plan"
  }
}

# 2. Update after contact
PATCH /api/v1/crm/leads/1234
{
  "status": "contacted",
  "notes": "Initial call completed. Scheduled demo for next week."
}

Scenario 2: Qualifying High-Value Leads

Context: Lead shows strong buying signals and meets BANT criteria

BANT Qualification:

Budget: Confirmed budget of $50K+
Authority: Speaking with decision maker
Need: Clear pain point identified
Timeline: Purchasing within 3 months

Workflow:

Verify BANT criteria during discovery call
Update lead score to reflect high qualification
Update estimated value based on discovered needs
Change status to qualified
Prepare for conversion to customer

API Calls:

bash

# 1. Update score
PATCH /api/v1/crm/leads/1234/score
{
  "behavioral_score": 48,
  "demographic_score": 42,
  "reason": "BANT qualified - confirmed budget, authority, need, timeline"
}

# 2. Update details
PATCH /api/v1/crm/leads/1234
{
  "status": "qualified",
  "estimated_value": 75000.00,
  "probability": 80,
  "notes": "BANT qualified. Budget: $75K, Authority: CTO, Need: Integration platform, Timeline: Q1 2026"
}

# 3. Qualify lead
POST /api/v1/crm/leads/1234/qualify

Scenario 3: Nurture Campaign Management

Context: Lead not ready to buy now, needs nurturing

Workflow:

Move lead to nurturing status
Tag with nurture campaign identifier
Add to automated email sequence
Monitor engagement scores
Re-engage when score increases

API Calls:

bash

# 1. Move to nurturing
PATCH /api/v1/crm/leads/1234
{
  "status": "nurturing",
  "tags": ["nurture-q1-2026", "mid-market"],
  "notes": "Not ready to buy. Budget approved Q1 2026. Added to nurture sequence."
}

# 2. Track engagement (when they open emails, download content)
PATCH /api/v1/crm/leads/1234/score
{
  "behavioral_score": 35,
  "reason": "Email engagement: 3 opens, 2 clicks, 1 content download"
}

Scenario 4: Lead Recycling

Context: Previously unqualified lead may now be qualified

Workflow:

Review unqualified leads quarterly
Research company changes (funding, growth, etc.)
Update demographic score if circumstances changed
Recycle promising leads back to contacted
Attempt re-engagement

API Calls:

bash

# 1. Update unqualified lead
PATCH /api/v1/crm/leads/5678
{
  "status": "recycled",
  "notes": "Company raised Series B funding. Decision maker still same. Recycling for re-engagement."
}

# 2. Assign to rep
POST /api/v1/crm/leads/5678/assign
{
  "user_id": 5
}

# 3. After successful contact
PATCH /api/v1/crm/leads/5678
{
  "status": "contacted",
  "estimated_value": 100000.00
}

Best Practices

1. Timely Follow-Up

Response Time Guidelines:

Hot leads (Score 80+): Contact within 1 hour
Warm leads (Score 60-79): Contact within 24 hours
Cool leads (Score 40-59): Contact within 1 week
Cold leads (Score <40): Add to nurture campaign

2. Data Quality

Ensure Clean Data:

Validate email addresses before creating leads
Use consistent naming conventions
Fill in all available contact information
Add meaningful tags for segmentation
Document notes after every interaction

3. Lead Scoring Accuracy

Maintain Scoring Integrity:

Review and adjust scoring models quarterly
Update scores after significant events
Don't inflate scores artificially
Use scoring to prioritize, not eliminate

4. Status Management

Follow Proper Status Flow:

Don't skip statuses without reason
Document why leads move backward (e.g., qualified → nurturing)
Use terminal statuses appropriately (converted, lost)
Never leave leads in "new" status for more than 48 hours

5. Assignment Strategy

Optimize Lead Distribution:

Use round-robin for fair distribution
Consider territory alignment
Balance workload across team
Reassign if no contact within SLA
Track assignment acceptance rates

6. Regular Cleanup

Maintain Database Health:

Review stale leads (no activity 30+ days)
Archive or delete duplicate leads
Update contact information when bounced
Mark inactive leads appropriately
Run deduplication processes monthly

Integration Points

With Opportunity Module

When a lead is qualified and ready for active sales pursuit, it can be converted to a customer and opportunity:

Lead status changes to converted
Customer record created from lead data
Opportunity created with estimated value
Historical lead data preserved
Refer to Lead Conversion Guide

With Activity Module

Track all interactions with leads:

Calls, emails, meetings automatically logged
Activities visible in lead timeline
Next follow-up actions scheduled
Activity completion updates last_activity_at
Refer to Activity Management Guide

With Campaign Module

Link leads to marketing campaigns:

Track campaign ROI by lead source
Measure conversion rates per campaign
Analyze lead quality by campaign
Automate lead scoring based on campaign engagement
Refer to Campaign Management Guide

Troubleshooting

Lead Creation Fails

Error: "This email address already exists in our system"

Cause: Duplicate lead with same email

Solution:

Search for existing lead: GET /api/v1/crm/leads/search?q={email}
Update existing lead instead of creating new one
If legitimately different person at same company, use different identifier

Score Not Updating

Issue: Lead score remains unchanged after activities

Possible Causes:

Automatic scoring not triggered
Integration with marketing platform disconnected
Manual update required

Solution:

bash

# Manually update score
PATCH /api/v1/crm/leads/{id}/score
{
  "behavioral_score": 45,
  "demographic_score": 40
}

Cannot Change Status

Error: "Invalid status transition"

Cause: Attempting invalid status change (e.g., new → converted)

Solution: Follow proper status progression:

new → contacted → qualified → converted
Check allowed transitions in Lead Lifecycle table

Lead Conversion Guide - Converting leads to customers
Customer Management - Managing converted customers
Opportunity Pipeline - Managing sales opportunities
Activity Management - Tracking lead interactions
Campaign Management - Marketing campaign integration

Lead Management Guide ​

Overview ​

Lead Lifecycle ​

Lead Status Progression ​

Lead Sources ​

Lead Scoring ​

Lead Score Components ​

Score Interpretation ​

Creating Leads ​

Basic Lead Creation ​

Listing and Filtering Leads ​

Get All Leads ​

Search Leads ​

Viewing Lead Details ​

Updating Leads ​

Assigning Leads ​

Assign Lead to User ​

Updating Lead Scores ​

Manual Score Update ​

Bulk Operations ​

Bulk Actions ​

Deleting Leads ​

Business Scenarios ​

Scenario 1: Website Lead Capture ​

Scenario 2: Qualifying High-Value Leads ​

Scenario 3: Nurture Campaign Management ​

Scenario 4: Lead Recycling ​

Best Practices ​

1. Timely Follow-Up ​

2. Data Quality ​

3. Lead Scoring Accuracy ​

4. Status Management ​

5. Assignment Strategy ​

6. Regular Cleanup ​

Integration Points ​

With Opportunity Module ​

With Activity Module ​

With Campaign Module ​

Troubleshooting ​

Lead Creation Fails ​

Score Not Updating ​

Cannot Change Status ​

Related Documentation ​

Lead Management Guide

Overview

Lead Lifecycle

Lead Status Progression

Lead Sources

Lead Scoring

Lead Score Components

Score Interpretation

Creating Leads

Basic Lead Creation

Listing and Filtering Leads

Get All Leads

Search Leads

Viewing Lead Details

Updating Leads

Assigning Leads

Assign Lead to User

Updating Lead Scores

Manual Score Update

Bulk Operations

Bulk Actions

Deleting Leads

Business Scenarios

Scenario 1: Website Lead Capture

Scenario 2: Qualifying High-Value Leads

Scenario 3: Nurture Campaign Management

Scenario 4: Lead Recycling

Best Practices

1. Timely Follow-Up

2. Data Quality

3. Lead Scoring Accuracy

4. Status Management

5. Assignment Strategy

6. Regular Cleanup

Integration Points

With Opportunity Module

With Activity Module

With Campaign Module

Troubleshooting

Lead Creation Fails

Score Not Updating

Cannot Change Status

Related Documentation