Lead Conversion Guide

Overview

Lead conversion is the critical process of transforming a qualified lead into an active customer. This guide explains the qualification process, conversion workflow, and best practices for successfully moving leads through the sales funnel to become paying customers.

Qualification Process

Before converting a lead, you must first qualify them to ensure they meet your criteria for a successful customer relationship.

BANT Qualification Framework

BANT is a proven qualification methodology:

Component	Description	Questions to Ask
Budget	Does the lead have budget allocated?	What budget range are you working with? When was it approved?
Authority	Are you speaking with the decision maker?	Who else is involved in this decision? What's your role in the buying process?
Need	Does the lead have a clear pain point?	What specific problem are you trying to solve? What happens if you don't solve it?
Timeline	When do they need a solution?	What's your target implementation date? What's driving this timeline?

Qualification Endpoint

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

Authentication: Required (Bearer token)

Request Body:

json

{
  "qualified": true,
  "qualification_notes": "BANT qualified: Budget $75K approved Q1, Authority confirmed (CTO decision maker), Need is integration platform for scaling operations, Timeline is 90 days for implementation.",
  "update_score": true,
  "behavioral_score": 48,
  "demographic_score": 42
}

Request Parameters:

qualified (boolean) - true to qualify, false to disqualify
qualification_notes (string) - Notes about qualification decision
disqualification_reason (string) - Required if qualified: false
update_score (boolean) - Whether to update lead score
behavioral_score (integer) - New behavioral score (0-50)
demographic_score (integer) - New demographic score (0-50)

Response (200 OK):

json

{
  "message": "Lead qualified successfully",
  "data": {
    "id": 1234,
    "email": "sarah.johnson@techcorp.com",
    "status": "qualified",
    "lead_score": {
      "total_score": 90,
      "behavioral_score": 48,
      "demographic_score": 42,
      "grade": "A",
      "temperature": "hot"
    },
    "qualified_at": "2025-12-17T14:30:00Z",
    "notes": "BANT qualified: Budget $75K approved Q1, Authority confirmed (CTO decision maker), Need is integration platform for scaling operations, Timeline is 90 days for implementation."
  }
}

Disqualifying a Lead

Request Body:

json

{
  "qualified": false,
  "disqualification_reason": "no_budget",
  "qualification_notes": "Company does not have budget allocated until Q3 2026. Moving to nurture campaign."
}

Common Disqualification Reasons:

no_budget - No budget allocated
no_authority - Cannot reach decision maker
no_need - No clear pain point or need
no_timeline - No urgency or defined timeline
bad_fit - Company/use case not a good fit
competitor - Already using competitor solution
not_ready - Interested but not ready to proceed

Response (200 OK):

json

{
  "message": "Lead disqualified",
  "data": {
    "id": 1234,
    "status": "disqualified",
    "lost_reason": "no_budget",
    "notes": "Company does not have budget allocated until Q3 2026. Moving to nurture campaign."
  }
}

Conversion Process

Converting a Lead to Customer

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

Authentication: Required (Bearer token)

Request Body:

json

{
  "create_customer": true,
  "create_opportunity": true,
  "opportunity_name": "TechCorp - Enterprise Integration Platform",
  "opportunity_amount": 75000.00,
  "opportunity_stage": "proposal",
  "opportunity_close_date": "2026-03-15",
  "opportunity_probability": 75,
  "notes": "Lead converted after successful demo and BANT qualification. Proposal to be delivered by Dec 20."
}

Request Parameters:

Customer Creation (required):

create_customer (boolean) - Must be true to convert lead

Opportunity Creation (optional):

create_opportunity (boolean) - Whether to create an opportunity
opportunity_name (string) - Required if create_opportunity: true
opportunity_amount (number) - Required if create_opportunity: true
opportunity_stage (string) - Required if create_opportunity: true
opportunity_close_date (date) - Required if create_opportunity: true
opportunity_probability (integer) - Win probability 0-100%

General:

notes (string) - Conversion notes

Response (200 OK):

json

{
  "message": "Lead converted successfully",
  "data": {
    "customer": {
      "id": 567,
      "customer_number": "CUST-000567",
      "first_name": "Sarah",
      "last_name": "Johnson",
      "company_name": "TechCorp Inc",
      "email": "sarah.johnson@techcorp.com",
      "phone": "+1-555-0123",
      "type": "individual",
      "status": "active",
      "lead_id": 1234,
      "created_at": "2025-12-17T15:00:00Z"
    },
    "opportunity": {
      "id": 890,
      "name": "TechCorp - Enterprise Integration Platform",
      "value": 75000.00,
      "stage": "proposal",
      "probability": 75,
      "expected_close_date": "2026-03-15",
      "customer_id": 567,
      "lead_id": 1234,
      "created_at": "2025-12-17T15:00:00Z"
    },
    "lead": {
      "id": 1234,
      "status": "converted",
      "converted_at": "2025-12-17T15:00:00Z"
    }
  }
}

What Happens During Conversion

Lead status changes to "converted"
Customer record created with lead data
Opportunity record created (if requested)
Lead's converted_at timestamp set
Customer linked to lead via lead_id
Opportunity linked to both customer and lead
Domain events fired for downstream processing

Conversion Scenarios

Scenario 1: Simple Conversion (Customer Only)

Use Case: Lead is ready to become a customer but no active opportunity yet

Workflow:

Qualify the lead
Convert to customer without opportunity
Create opportunity later when deal specifics are known

API Calls:

bash

# Step 1: Qualify
POST /api/v1/crm/leads/1234/qualify
{
  "qualified": true,
  "qualification_notes": "BANT qualified. Ready for conversion."
}

# Step 2: Convert (customer only)
POST /api/v1/crm/leads/1234/convert
{
  "create_customer": true,
  "create_opportunity": false,
  "notes": "Converting to customer. Will create opportunity when deal structure is finalized."
}

When to Use:

Early stage qualification
Customer wants to start small without commitment
Deal specifics not yet determined
Trial or proof-of-concept period

Scenario 2: Full Conversion (Customer + Opportunity)

Use Case: Lead is qualified and has specific opportunity with defined value

Workflow:

Conduct discovery calls and BANT qualification
Determine opportunity value and timeline
Convert lead to customer and create opportunity simultaneously
Move opportunity through sales pipeline

API Calls:

bash

# Step 1: Qualify
POST /api/v1/crm/leads/1234/qualify
{
  "qualified": true,
  "qualification_notes": "Full BANT qualification completed. Budget $75K, Authority CTO, Need integration, Timeline 90 days.",
  "update_score": true,
  "behavioral_score": 48,
  "demographic_score": 42
}

# Step 2: Convert with opportunity
POST /api/v1/crm/leads/1234/convert
{
  "create_customer": true,
  "create_opportunity": true,
  "opportunity_name": "TechCorp - Enterprise Integration Platform",
  "opportunity_amount": 75000.00,
  "opportunity_stage": "needs_analysis",
  "opportunity_close_date": "2026-03-15",
  "opportunity_probability": 60,
  "notes": "Converted after successful demo. Customer confirmed budget and timeline. Moving to proposal stage."
}

When to Use:

Clear opportunity with defined scope
Budget and timeline confirmed
Decision maker identified and engaged
Ready to create formal proposal

Scenario 3: Multi-Stage Conversion

Use Case: Large enterprise deal requiring multiple touchpoints

Workflow:

Initial qualification (basic BANT)
Discovery calls with stakeholders
Technical validation/POC
Final qualification with executive sponsor
Conversion with high-value opportunity

API Calls:

bash

# Step 1: Initial qualification
POST /api/v1/crm/leads/1234/qualify
{
  "qualified": true,
  "qualification_notes": "Initial qualification passed. Moving to discovery phase.",
  "update_score": true,
  "behavioral_score": 35,
  "demographic_score": 40
}

# Step 2: Update after discovery (multiple calls)
PATCH /api/v1/crm/leads/1234
{
  "estimated_value": 250000.00,
  "probability": 40,
  "notes": "Discovery completed with IT team. 5 departments will use platform. Enterprise deployment required."
}

# Step 3: Update score after POC
PATCH /api/v1/crm/leads/1234/score
{
  "behavioral_score": 45,
  "demographic_score": 45,
  "reason": "Successful POC completion. High engagement from technical team."
}

# Step 4: Final qualification with executive
POST /api/v1/crm/leads/1234/qualify
{
  "qualified": true,
  "qualification_notes": "Executive sponsor confirmed. Budget $250K approved. Timeline Q1 2026 go-live.",
  "update_score": true,
  "behavioral_score": 50,
  "demographic_score": 48
}

# Step 5: Convert with opportunity
POST /api/v1/crm/leads/1234/convert
{
  "create_customer": true,
  "create_opportunity": true,
  "opportunity_name": "TechCorp Enterprise - Dept-wide Platform Deployment",
  "opportunity_amount": 250000.00,
  "opportunity_stage": "proposal",
  "opportunity_close_date": "2026-02-28",
  "opportunity_probability": 70,
  "notes": "Enterprise deal. 5 departments. Executive sponsor engaged. Legal review in progress."
}

Characteristics:

Multiple stakeholders involved
Technical validation required
Higher value (>$100K)
Longer sales cycle (3-6 months)
Executive-level approval needed

Scenario 4: Conversion After Nurture Campaign

Use Case: Lead was previously unqualified, nurtured, now ready

Workflow:

Lead initially disqualified (no budget)
Added to nurture campaign
Re-engaged after 6 months
Circumstances changed (budget now available)
Re-qualified and converted

API Calls:

bash

# Step 1: Initial disqualification
POST /api/v1/crm/leads/1234/qualify
{
  "qualified": false,
  "disqualification_reason": "no_budget",
  "qualification_notes": "Good fit but no budget until Q1 2026. Adding to nurture campaign."
}

# Step 2: Move to nurturing
PATCH /api/v1/crm/leads/1234
{
  "status": "nurturing",
  "tags": ["nurture-q1-2026", "budget-pending"]
}

# [6 months pass, nurture campaign continues]

# Step 3: Re-engagement
PATCH /api/v1/crm/leads/1234
{
  "status": "contacted",
  "notes": "Re-engaged. Budget now approved for Q1 2026."
}

# Step 4: Re-qualification
POST /api/v1/crm/leads/1234/qualify
{
  "qualified": true,
  "qualification_notes": "Budget approved. Still speaking with same decision maker. Need remains strong. Timeline confirmed.",
  "update_score": true,
  "behavioral_score": 42,
  "demographic_score": 40
}

# Step 5: Conversion
POST /api/v1/crm/leads/1234/convert
{
  "create_customer": true,
  "create_opportunity": true,
  "opportunity_name": "TechCorp - Integration Platform (Nurture Win)",
  "opportunity_amount": 75000.00,
  "opportunity_stage": "qualification",
  "opportunity_close_date": "2026-03-31",
  "opportunity_probability": 65,
  "notes": "Successfully nurtured lead. Budget approved in Q1 as expected. Moving forward with proposal."
}

Key Success Factors:

Timing of re-engagement aligned with budget cycle
Maintained relationship during nurture period
Decision maker remained consistent
Original need still relevant

Conversion Best Practices

1. Qualify Before Converting

Why: Ensures customer fit and higher likelihood of success

Qualification Checklist:

[ ] Budget confirmed and approved
[ ] Decision maker identified and engaged
[ ] Clear need/pain point articulated
[ ] Timeline defined and realistic
[ ] Technical requirements understood
[ ] Company is good fit for solution
[ ] No blocking competitive relationships

Never Skip Qualification

Converting unqualified leads leads to:

Lower close rates
Longer sales cycles
Higher churn rates
Wasted resources
Poor customer experience

2. Document Thoroughly

What to Document:

Qualification criteria met (BANT)
Key stakeholders and their roles
Specific needs and pain points
Competitive landscape
Decision-making process and timeline
Budget approval process
Technical requirements
Success criteria

Where to Document:

json

{
  "qualification_notes": "Detailed BANT assessment...",
  "notes": "Stakeholders: CTO (decision maker), IT Director (champion), CFO (budget authority). Pain point: Manual integration consuming 20 hours/week. Timeline: Must implement before Q2 busy season.",
  "custom_fields": {
    "stakeholders": ["CTO", "IT Director", "CFO"],
    "competitors_evaluated": ["Competitor A", "Competitor B"],
    "technical_requirements": ["API access", "SSO", "99.9% uptime SLA"]
  }
}

3. Create Opportunities Immediately

When to Create Opportunity:

Clear deal with defined scope
Specific dollar amount identified
Timeline for decision established
Multiple touchpoints planned

Why Create Immediately:

Prevents leads from falling through cracks
Enables pipeline forecasting
Tracks opportunity through stages
Maintains historical record

4. Set Realistic Probabilities

Probability Guidelines:

Opportunity Stage	Typical Probability
Prospecting	10-20%
Qualification	20-30%
Needs Analysis	30-40%
Proposal	50-60%
Negotiation	60-80%
Verbal Commitment	80-90%
Closed Won	100%

Adjust Based On:

BANT qualification strength
Competitive situation
Budget approval status
Stakeholder engagement level
Timeline urgency

5. Maintain Lead History

After Conversion:

Lead record remains in database
Status set to "converted"
Link preserved to customer and opportunity
Historical activities maintained
Lead score history retained

Why Maintain History:

Attribution tracking (which marketing channels work)
Sales cycle analysis (time from lead to customer)
Rep performance measurement
Campaign ROI calculation
Future reference for similar leads

6. Handoff to Account Management

For Enterprise Customers: After conversion, hand off to account management team:

Brief account manager on customer background
Transfer notes and qualification details
Introduce account manager to customer
Transition from sales to service mode
Set expectations for next steps

Common Conversion Challenges

Challenge 1: Incomplete Qualification

Problem: Attempting to convert before full qualification

Symptoms:

Missing budget information
Can't reach decision maker
Unclear timeline
Vague need definition

Solution:

bash

# Don't convert yet - update lead for additional discovery
PATCH /api/v1/crm/leads/1234
{
  "status": "contacted",
  "notes": "Need more discovery: budget not confirmed, need to reach VP level decision maker. Scheduling follow-up call next week."
}

Challenge 2: Multiple Decision Makers

Problem: Complex buying committee, unclear primary contact

Solution:

Identify champion within organization
Map organizational structure
Create customer record for primary contact
Use opportunity notes to track all stakeholders
Create activities for each stakeholder interaction

bash

# Convert with champion as primary customer
POST /api/v1/crm/leads/1234/convert
{
  "create_customer": true,
  "create_opportunity": true,
  "opportunity_name": "TechCorp Enterprise (Committee: 5 stakeholders)",
  "opportunity_amount": 200000.00,
  "notes": "Primary: Sarah Johnson (CTO, decision maker). Committee: IT Director (champion), CFO (budget), VP Ops (user), Legal (contracts). Champion is IT Director Mike Chen."
}

Challenge 3: Budget Timing Mismatch

Problem: Lead qualified but budget not available until future date

Solution:

bash

# Qualify but don't convert yet
POST /api/v1/crm/leads/1234/qualify
{
  "qualified": true,
  "qualification_notes": "Fully qualified but budget not available until Q2 2026. All other BANT criteria met. Maintaining engagement until budget release."
}

# Update to nurturing
PATCH /api/v1/crm/leads/1234
{
  "status": "nurturing",
  "tags": ["budget-q2-2026", "qualified-waiting"],
  "notes": "Budget approved but not released until Q2. Confirmed we're the vendor of choice. Will convert when budget available."
}

Challenge 4: Opportunity Value Unknown

Problem: Lead is qualified but exact deal size unclear

Solution:

bash

# Convert to customer first, create opportunity later
POST /api/v1/crm/leads/1234/convert
{
  "create_customer": true,
  "create_opportunity": false,
  "notes": "Customer qualified and ready to proceed. Starting with basic package, will expand. Creating opportunity once deployment plan is finalized."
}

# Later, create opportunity when value is known
POST /api/v1/crm/opportunities
{
  "name": "TechCorp - Platform Expansion",
  "customer_id": 567,
  "lead_id": 1234,
  "value": 50000.00,
  "stage": "proposal",
  "expected_close_date": "2026-02-28"
}

Integration Points

With Customer Module

After conversion, customer management takes over:

Customer profile created with complete information
Customer health scoring begins
Account activities tracked separately
Upsell/cross-sell opportunities identified
Refer to Customer Management Guide

With Opportunity Module

Created opportunities flow into sales pipeline:

Opportunity moves through defined stages
Pipeline forecasting includes converted opportunities
Stage-specific activities tracked
Win/loss analysis conducted
Refer to Opportunity Pipeline Guide

With Activity Module

All historical activities preserved:

Lead activities remain visible
Customer activities begin accumulating
Opportunity activities tracked separately
Complete interaction timeline maintained
Refer to Activity Management Guide

Metrics and Reporting

Key Conversion Metrics

Lead Conversion Rate:

(Number of Converted Leads / Total Qualified Leads) × 100

Average Time to Conversion:

Average days from Lead Created to Lead Converted

Lead Source Conversion Rate:

Compare conversion rates across different lead sources

Sales Cycle Length:

Average days from first contact to closed-won opportunity

Tracking Conversion Success

Monitor These KPIs:

Conversion rate by source
Conversion rate by assigned rep
Time in each status before conversion
Opportunity win rate from converted leads
Average deal size by lead source
Cost per conversion by channel

Troubleshooting

Cannot Convert Lead

Error: "Lead must be qualified before conversion"

Solution:

bash

# Qualify first
POST /api/v1/crm/leads/1234/qualify
{
  "qualified": true,
  "qualification_notes": "BANT qualified"
}

# Then convert
POST /api/v1/crm/leads/1234/convert
{
  "create_customer": true
}

Conversion Creates Duplicate Customer

Error: "Customer with this email already exists"

Cause: Email address already in customer database

Solution:

Check if customer already exists: GET /api/v1/crm/customers/search?q={email}
If duplicate, update existing customer instead
Link lead to existing customer manually
Create opportunity for existing customer

Opportunity Not Created

Issue: Customer created but opportunity missing

Possible Causes:

create_opportunity: false in request
Missing required opportunity fields
Validation error in opportunity data

Solution: Create opportunity separately:

bash

POST /api/v1/crm/opportunities
{
  "name": "Opportunity Name",
  "customer_id": 567,
  "lead_id": 1234,
  "value": 75000.00,
  "stage": "proposal",
  "expected_close_date": "2026-03-15"
}

Lead Management Guide - Managing leads before conversion
Customer Management - Managing converted customers
Opportunity Pipeline - Managing sales opportunities
Activity Management - Tracking customer interactions
Customer Health Scoring - Monitoring customer health

Lead Conversion Guide ​

Overview ​

Qualification Process ​

BANT Qualification Framework ​

Qualification Endpoint ​

Disqualifying a Lead ​

Conversion Process ​

Converting a Lead to Customer ​

Conversion Scenarios ​

Scenario 1: Simple Conversion (Customer Only) ​

Scenario 2: Full Conversion (Customer + Opportunity) ​

Scenario 3: Multi-Stage Conversion ​

Scenario 4: Conversion After Nurture Campaign ​

Conversion Best Practices ​

1. Qualify Before Converting ​

2. Document Thoroughly ​

3. Create Opportunities Immediately ​

4. Set Realistic Probabilities ​

5. Maintain Lead History ​

6. Handoff to Account Management ​

Common Conversion Challenges ​

Challenge 1: Incomplete Qualification ​

Challenge 2: Multiple Decision Makers ​

Challenge 3: Budget Timing Mismatch ​

Challenge 4: Opportunity Value Unknown ​

Integration Points ​

With Customer Module ​

With Opportunity Module ​

With Activity Module ​

Metrics and Reporting ​

Key Conversion Metrics ​

Tracking Conversion Success ​

Troubleshooting ​

Cannot Convert Lead ​

Conversion Creates Duplicate Customer ​

Opportunity Not Created ​

Related Documentation ​

Lead Conversion Guide

Overview

Qualification Process

BANT Qualification Framework

Qualification Endpoint

Disqualifying a Lead

Conversion Process

Converting a Lead to Customer

Conversion Scenarios

Scenario 1: Simple Conversion (Customer Only)

Scenario 2: Full Conversion (Customer + Opportunity)

Scenario 3: Multi-Stage Conversion

Scenario 4: Conversion After Nurture Campaign

Conversion Best Practices

1. Qualify Before Converting

2. Document Thoroughly

3. Create Opportunities Immediately

4. Set Realistic Probabilities

5. Maintain Lead History

6. Handoff to Account Management

Common Conversion Challenges

Challenge 1: Incomplete Qualification

Challenge 2: Multiple Decision Makers

Challenge 3: Budget Timing Mismatch

Challenge 4: Opportunity Value Unknown

Integration Points

With Customer Module

With Opportunity Module

With Activity Module

Metrics and Reporting

Key Conversion Metrics

Tracking Conversion Success

Troubleshooting

Cannot Convert Lead

Conversion Creates Duplicate Customer

Opportunity Not Created

Related Documentation