Skip to content

Prelead Management Use Cases (PRE)

Module Purpose: Manage high-volume raw data from campaigns, directories, and email integrations before they qualify as CRM leads.

Use Case Quick Reference

ID Title Priority
PRE-001 Raw Data Ingestion (Excel/API) P1
PRE-002 3-Level Screening Workflow P1
PRE-003 Source Attribution & Database Naming P1
PRE-004 Raw-to-Recheck Mapping (De-dupe) P1
PRE-005 Transfer to BD / Mapped User P2
PRE-006 Performance Alerts (Screening Variance) P2

UC-PRE-001: Raw Data Ingestion (Excel/API)

Purpose: Accept and process high-volume raw prelead data from Excel uploads, Outlook integration, and third-party APIs (IndiaMart, TradeIndia) into the Raw Prelead bucket for downstream screening.

Property Value
Actor Back-office Team, System Integration Engine
Trigger User uploads Excel file OR Outlook folder sync interval (every 15 min) OR API webhook
Preconditions - Excel template matches defined schema
- Outlook OAuth token valid
- API credentials configured
Priority P1

Main Success Scenario

  1. Upload Initiation
  2. User selects Excel file via file picker OR System polls Outlook folder

  3. System validates file extension (.xlsx, .csv) and size limit (< 10MB)

  4. Field Mapping

  5. System displays column mapper UI
  6. User maps columns to fields: Buyer Name, Address, Mobile, Email, Product Name
  7. For source type "Directories": Additional fields Directory Name, Vendor Name appear

  8. For source type "Database": Additional field Database Name appears

  9. Data Extraction & Enrichment

  10. System parses rows and extracts values
  11. For Outlook emails: System captures email body as snapshot (HTML → PNG), attaches original .eml file

  12. For API sources: System stores raw JSON payload as attachment

  13. Auto-Fill & Validation

  14. System auto-generates Subject: [Customer Name] + [Product Name] (or "Unknown" if missing)
  15. System performs basic validation: Email regex, Phone number format (10-15 digits)

  16. Invalid rows are flagged but not rejected

  17. Batch Creation

  18. System creates Prelead records with status = "Raw"
  19. Each record is assigned unique ID: PRE-YYYYMMDD-XXXXX

  20. System links all attachments (PDF, JPG, PNG) to the Prelead ID

  21. Queue for Screening

  22. System pushes batch to Level 1 Screening Queue
  23. System emits event: prelead.batch.created

Alternative Flows

A1: Duplicate File Upload - At step 1, if file hash (MD5) matches existing upload within 24h - System shows warning: "This file was uploaded X hours ago" - User can proceed or cancel

A2: Column Mismatch - At step 2, if required columns missing (Buyer Name OR Mobile/Email) - System blocks upload, highlights missing columns in red

A3: Outlook Sync Failure - At step 1, if OAuth token expired - System triggers re-authentication flow via popup - User re-authorizes, sync resumes

Observability

Metrics: 

prelead_uploads_total{source="excel|outlook|api", status="success|failed"}
prelead_records_created{source="excel|outlook|api"}
prelead_validation_errors{field="email|phone|name"}

Logs: 

{
  "event": "prelead_batch_uploaded",
  "user_id": "user_123",
  "source": "excel",
  "file_name": "campaign_leads_jan.xlsx",
  "rows_total": 450,
  "rows_valid": 442,
  "rows_invalid": 8,
  "duration_ms": 1200
}

Acceptance Criteria

  • Processes Excel files up to 10MB / 5000 rows
  • Supports concurrent uploads (up to 10 users)
  • Captures email snapshots within 2 seconds
  • Auto-generates subject for 100% of records
  • Flags validation errors without blocking upload
  • Links all attachments (PDF, JPG, email) to Prelead ID
  • Emits batch creation event for downstream processing
  • Handles Outlook OAuth refresh automatically

UC-PRE-002: 3-Level Screening Workflow

Purpose: Validate raw preleads through a progressive 3-tier screening process (Level 1 → Level 2 → Level 3) with quality control alerts to ensure only high-quality leads reach sales teams.

Property Value
Actor Marketing Screening Team, Quality Control Manager
Trigger Prelead moves to "Raw" status OR screening level fails
Preconditions - Prelead exists with status = "Raw"
- Screening team members assigned to levels
- Performance thresholds configured
Priority P1

Main Success Scenario

  1. Level 1: Fresh Validation
  2. Screener opens Prelead from Level 1 Queue
  3. Screener verifies: Company name is real, Product is valid, Contact info looks legitimate
  4. Screener selects outcome: "Qualified" OR "Not Qualified"
  5. If "Qualified": Prelead moves to Approval Queue

  6. If "Not Qualified": Prelead moves to Level 2 Queue

  7. Level 2: Re-check & Deep Validation

  8. Different screener opens Prelead from Level 2 Queue
  9. System shows Level 1 screener's name and reason for rejection
  10. Screener performs deeper validation: Google search company, verify domain registration, check social profiles
  11. Screener selects outcome: "Qualified" OR "Not Qualified"
  12. If "Qualified": Prelead moves to Approval Queue (with flag: "Level 2 Recovery")

  13. If "Not Qualified": Prelead moves to Level 3 Queue

  14. Level 3: Final Escalation

  15. Manager/Senior Screener reviews Prelead from Level 3 Queue
  16. System shows both Level 1 and Level 2 screener names and reasons
  17. Manager makes final decision: "Qualified" OR "Drop"
  18. If "Qualified": Prelead moves to Approval Queue (with flag: "Level 3 Escalation")

  19. If "Drop": Prelead status set to "Rejected", archived

  20. Quality Analytics Trigger

  21. System calculates screening variance: (Level 2 Recoveries / Level 1 Rejections) * 100
  22. If variance > 30% for a specific screener in a day:
    • System emits alert: screening.quality.variance_high
    • Email sent to Manager: "Screener X has high variance (45%), review needed"

Alternative Flows

A1: Underperformance Alert - During Level 1, if screener processes < 10 preleads/hour for 2 consecutive hours - System triggers alert: screening.performance.low - Manager receives notification

A2: Batch Qualification - At any level, if screener selects multiple preleads (bulk action) - System applies same decision to all - System logs: bulk_decision_applied: {count: 50, decision: "qualified"}

Observability

Metrics: 

prelead_screening_decisions_total{level="1|2|3", decision="qualified|rejected"}
prelead_screening_duration_seconds{level="1|2|3"}
prelead_screening_variance_percent{screener_id="user_X"}
prelead_queue_depth{level="1|2|3"}

Logs: 

{
  "event": "prelead_screening_completed",
  "prelead_id": "PRE-20260108-00123",
  "level": 1,
  "screener_id": "user_45",
  "decision": "not_qualified",
  "reason": "Invalid company – no web presence",
  "duration_seconds": 45
}

Acceptance Criteria

  • Prelead cannot skip levels (must go 1 → 2 → 3 sequentially)
  • Each level is assigned to different screeners (no self-review)
  • Variance alert triggers if Level 2 recoveries exceed 30% for any screener
  • Underperformance alert triggers if < 10 preleads/hour for 2 hours
  • Manager can view historical screening decisions for training purposes
  • Queue depth visible in real-time dashboard

UC-PRE-003: Source Attribution & Database Naming

Purpose: Capture and categorize the source of each prelead (Campaign, Directory, Database, Referral) with source-specific metadata fields to enable accurate ROI tracking and lead quality analysis by channel.

Property Value
Actor Back-office User, System
Trigger During prelead creation (PRE-001) OR manual edit
Preconditions - Source type picklist configured
- Directory/Database masters exist
Priority P1

Main Success Scenario

  1. Source Type Selection
  2. User selects Lead Source from dropdown:
    • Campaign (Marketing/PRD/Industries)
    • Directory (Business directories)
    • Database (Old/New/Purchased)
    • Referral (Employee/Field Visit)

  3. System dynamically shows relevant fields based on selection

  4. Campaign Source

  5. If source = "Campaign":
    • System shows: Campaign Name (dropdown from Campaign master)
    • System shows: Industry (picklist: Pharma, Chemicals, Food, etc.)
    • System shows: Product Category (multi-select)
  6. User selects campaign: "Zinc Oxide Q1 2026"

  7. System auto-tags prelead with campaign ID for ROI tracking

  8. Directory Source

  9. If source = "Directory":
    • System shows: Directory Name (text field)
    • System shows: Directory Type (picklist: India Mart, Trade India, Alibaba, etc.)
    • System shows: Vendor Name (who we purchased from)

  10. User enters: "India Mart", "Trade India Platform", "Vendor XYZ"

  11. Database Source

  12. If source = "Database":
    • System shows: Database Name (text field)
    • System shows: Database Type (picklist: Old/New/Purchased)
    • System shows: Industry (picklist)

  13. User enters: "Chemical Buyers DB 2025", "Purchased", "Chemicals"

  14. Referral Source

  15. If source = "Referral":
    • System shows: Employee Name (dropdown from Employee master)
    • System shows: Referral Type (picklist: Employee/Field Visit)

  16. For Field Visit: Links to EML-014 Route Planning

  17. Source Metadata Storage

  18. System saves all source-specific fields to prelead record
  19. System increments counter: source_stats.campaign_X.leads_generated++
  20. Data available for reporting: "Leads by Source", "ROI by Campaign"

Observability

Metrics: 

prelead_sources_total{source_type="campaign|directory|database|referral"}
prelead_campaign_performance{campaign_id="camp_123", status="qualified|rejected"}

Logs: 

{
  "event": "prelead_source_attributed",
  "prelead_id": "PRE-20260108-00999",
  "source_type": "campaign",
  "source_details": {
    "campaign_name": "Zinc Oxide Q1 2026",
    "industry": "Pharma",
    "product_category": ["Zinc Oxide", "Magnesium Oxide"]
  }
}

Acceptance Criteria

  • Dynamic field rendering based on source type selection
  • Campaign dropdown populated from Campaign master
  • Directory/Database fields allow free-text entry
  • Employee dropdown populated for Referral source
  • Source metadata stored in structured JSON field
  • Enables reporting by source type and specific source
  • Cross-links Field Visit referrals to Route Planning (EML-014)

See Also

UC-PRE-004: Raw-to-Recheck Mapping (De-dupe)

Purpose: Automatically detect and flag potential duplicate preleads by matching phone numbers, email domains, and company identifiers (CIN/PAN) against existing customer and contact masters to prevent redundant data entry.

Property Value
Actor System De-duplication Engine, Validation APIs
Trigger Prelead moves from "Raw" status to "Re-check" queue
Preconditions - Customer/Contact masters populated
- RocketReach API key configured
- Phone validation service active
Priority P1

Main Success Scenario

  1. Prelead Entry to Re-check Queue
  2. System retrieves prelead from Level 1 screening queue

  3. System extracts key fields: phone, email, company_name, domain

  4. Phone Number Matching

  5. System queries Contact master: SELECT * WHERE phone = prelead.phone
  6. If match found (exact 10-15 digit match):
    • System displays: "⚠️ This phone (91-XXXXXXXXXX) is mapped to Contact Name at Company ABC"
    • System shows contact's full profile + transaction history

  7. If no match: Proceed to step 3

  8. Email Domain Matching

  9. System extracts domain from email: user@domain.com → domain.com
  10. System queries Customer master: SELECT * WHERE email_domain = 'domain.com'
  11. If match found:
    • System displays: "⚠️ This domain belongs to Company ABC (CID: CUST-12345)"
    • System suggests: "Link as Same Customer or Group Company?"

  12. If no match: Proceed to step 4

  13. CIN/PAN Similarity Check (Cross-link to EML-013)

  14. If prelead has CIN or PAN in notes/attachments:

    • System calls fuzzy match service: similarity(prelead.cin, master.cin) >= 95%
    • If similar CIN/PAN found:
    • System blocks: "🛑 Duplicate detected – CIN matches Company XYZ"
    • System requires manager override to proceed

  15. Email Validation via RocketReach

  16. System calls RocketReach API: validate_email(prelead.email)
  17. API returns: {valid: true, deliverable: true, company: "ABC Corp"}

  18. If email invalid: Flag prelead with "Email validation failed"

  19. Consolidation & Flagging

  20. System creates De-dupe Report attached to prelead:
    • Matched contacts (if any)
    • Matched customers (if any)
    • Validation status (phone valid, email valid)
  21. System updates prelead status: "Re-check – Matches Found" OR "Re-check – No Matches"

Alternative Flows

A1: Multiple Phone Matches - At step 2, if phone matches 2+ contacts (e.g., shared office line) - System displays all matches in dropdown - Screener selects primary contact manually

A2: Domain Match with Group Company - At step 3, if domain matches existing customer - Screener can tag as "Group Company" instead of "Same Customer" - System links both entities under Group hierarchy (Cross-ref: MST-001)

A3: RocketReach API Timeout - At step 5, if API call takes > 5 seconds - System skips email validation, logs warning - Prelead proceeds with flag: "Email validation pending"

Observability

Metrics: 

prelead_dedup_checks_total{match_type="phone|domain|cin"}
prelead_dedup_matches_found{match_type="phone|domain|cin"}
prelead_email_validation_calls{status="success|failed|timeout"}
prelead_dedup_duration_seconds

Logs: 

{
  "event": "prelead_dedup_completed",
  "prelead_id": "PRE-20260108-00456",
  "phone_matches": 1,
  "domain_matches": 1,
  "cin_matches": 0,
  "email_valid": true,
  "duration_ms": 850
}

Acceptance Criteria

  • Checks phone against all contact records (exact match)
  • Checks email domain against all customer records
  • Performs CIN/PAN fuzzy match at 95% similarity threshold
  • Blocks duplicate creation if CIN match above threshold
  • Integrates with RocketReach for email validation
  • Displays all matches with full context (contact name, company, history)
  • Allows manual override with manager approval
  • Completes de-dupe check within 2 seconds (excluding external API calls)

See Also

UC-PRE-005: Transfer to BD / Mapped User

Purpose: Automatically detect when a prelead's customer is already assigned to an existing sales user and trigger an approval workflow to either transfer ownership, allow dual-handling, or drop the duplicate prelead.

Property Value
Actor System Workflow Engine, Mapped User (Owner), Prelead User
Trigger Prelead passes de-dupe check AND customer master has assigned_user_id populated
Preconditions - Customer master exists with active owner
- Prelead user has permission to request transfers
- Notification service configured
Priority P2

Main Success Scenario

  1. Ownership Conflict Detection
  2. During PRE-004 de-dupe, system identifies customer match: "Company ABC"
  3. System checks Customer master: assigned_user_id = user_123 (Sales Rep: John Doe)
  4. System compares: prelead.created_by = user_456 (Marketing Rep: Jane Smith)

  5. Conflict detected: Prelead user ≠ Customer owner

  6. Transfer Request Creation

  7. System creates Transfer Request record:
    • prelead_id: PRE-20260108-00789
    • requesting_user: user_456 (Jane)
    • target_user: user_123 (John)
    • status: "Pending Approval"

  8. System emits notification: transfer.request.created

  9. Owner Notification

  10. System sends email + in-app notification to John: 

    Subject: Transfer Request for Company ABC

Jane Smith wants to work on a prelead for **Company ABC** (your customer).

Prelead Details:
- Product: Zinc Oxide
- Source: India Mart
- Contact: contact@companyabc.com

Actions: [Approve] [Transfer to Me] [Drop]

  11. Owner Decision - Approval Path

  12. John clicks [Approve]
  13. System updates:
    • Prelead status: "Approved – Dual Handling"
    • Prelead owner remains: user_456 (Jane)
    • Prelead field assistant_user_id: user_123 (John) – receives CC on all updates

  14. Jane can proceed with quote

  15. Owner Decision - Transfer Path

  16. John clicks [Transfer to Me]
  17. System updates:
    • Prelead owner: user_123 (John)
    • Prelead field assistant_user_id: user_456 (Jane) – receives CC, can assist
    • Notification sent to Jane: "Prelead transferred to John, you're added as Assistant"

  18. John takes over quote process

  19. Owner Decision - Drop Path

  20. John clicks [Drop] + enters reason: "Duplicate enquiry from last week"
  21. System updates:
    • Prelead status: "Rejected – Owner Veto"
    • Prelead archived, Jane cannot proceed
  22. Jane receives notification with rejection reason

Alternative Flows

A1: No Response from Owner (72 hours) - At step 3, if John doesn't respond within 72 hours - System auto-escalates to John's Manager - Manager can approve/transfer/drop - If manager also doesn't respond in 24h: Auto-approve (Jane proceeds)

A2: Owner on Leave - At step 1, if John's status = "On Leave" - System checks for temporary_owner (e.g., John's backup: user_789) - Transfer request sent to backup user - Original approval workflow applies

A3: Prelead User Requests Drop - Before reaching this UC, Jane can voluntarily drop the prelead if she sees it matches existing customer - No approval needed, prelead auto-archived

Observability

Metrics: 

prelead_transfer_requests_total{decision="approve|transfer|drop|timeout"}
prelead_transfer_request_duration_seconds
prelead_assistant_assignments_total

Logs: 

{
  "event": "transfer_request_decided",
  "prelead_id": "PRE-20260108-00789",
  "requesting_user": "user_456",
  "target_user": "user_123",
  "decision": "approve",
  "decider": "user_123",
  "duration_hours": 2.5
}

Acceptance Criteria

  • Detects ownership conflict if customer has assigned_user_id
  • Creates transfer request with all context (product, source, contact)
  • Sends notification to mapped user within 30 seconds
  • Supports 3 decision paths: Approve, Transfer, Drop
  • Assigns Assistant role correctly based on decision
  • Auto-escalates to manager if no response in 72 hours
  • Auto-approves if manager also doesn't respond in 24 hours
  • Handles owner on leave by routing to temporary_owner

See Also

UC-PRE-006: Performance Alerts (Screening Variance)

Purpose: Monitor screening quality by detecting variance between Level 1 and Level 2 decisions, and employee productivity by tracking screening throughput, triggering management alerts when thresholds are breached.

Property Value
Actor System Analytics Engine, Quality Control Manager
Trigger End of day batch job (runs at 11:59 PM) OR real-time after every 50 screening decisions
Preconditions - Screening decisions logged in database
- Performance thresholds configured
- Manager notification emails set up
Priority P2

Main Success Scenario

  1. Daily Analytics Aggregation
  2. At 11:59 PM, system queries screening decisions for the day
  3. System groups by screener: user_45, user_67, user_89

  4. For each screener, system calculates:

    • Level 1 rejections: COUNT(level=1, decision='rejected')
    • Level 2 recoveries: COUNT(level=2, decision='qualified') of preleads they rejected at L1
    • Variance: (L2_recoveries / L1_rejections) * 100

  5. Variance Threshold Check

  6. System checks if variance > 30% for any screener
  7. Example: user_45 rejected 100 preleads at L1, but 45 were qualified at L2 → 45% variance

  8. If variance > 30%:

    • System creates Alert: screening.quality.variance_high
    • Alert severity: "Warning" (30-50%), "Critical" (>50%)

  9. Productivity Threshold Check

  10. System calculates hourly throughput: preleads_screened / hours_worked

  11. If throughput < 10 preleads/hour for 2+ consecutive hours:

    • System creates Alert: screening.performance.low
    • Alert severity: "Warning"

  12. Manager Notification

  13. System sends email to Quality Control Manager: 

    Subject: [Alert] Screening Quality Issue – User 45

**Variance Alert**:
- Screener: Jane Doe (user_45)
- Level 1 Rejections: 100
- Level 2 Recoveries: 45
- **Variance: 45%** (Threshold: 30%)

**Recommended Action**: Review training materials with Jane

[View Detailed Report]

  14. Alert Dashboard Update

  15. System updates real-time dashboard widget:

    • Today's Variance Alerts: 2
    • Week's Productivity Alerts: 5
    • Trend graph: Variance by screener over 30 days

  16. Historical Tracking

  17. System stores alert in performance_alerts table
  18. Manager can view historical alerts and resolution notes
  19. Used for quarterly performance reviews

Alternative Flows

A1: Real-time Alert (50 Decision Trigger) - Instead of waiting until EOD, system checks variance after every 50 decisions - If real-time variance > 40%: Immediate alert to manager - Allows for same-day intervention

A2: Consecutive Days Above Threshold - If screener has variance > 30% for 3 consecutive days - Alert escalates to Senior Management - Suggests formal retraining or role reassignment

Observability

Metrics: 

prelead_screening_variance_percent{screener_id="user_X", period="daily|weekly"}
prelead_screening_throughput_per_hour{screener_id="user_X"}
prelead_performance_alerts_fired{alert_type="variance|productivity", severity="warning|critical"}

Logs: 

{
  "event": "performance_alert_fired",
  "alert_type": "screening_variance",
  "screener_id": "user_45",
  "screener_name": "Jane Doe",
  "l1_rejections": 100,
  "l2_recoveries": 45,
  "variance_percent": 45,
  "threshold_percent": 30,
  "severity": "critical",
  "notified_manager": "manager_01"
}

Acceptance Criteria

  • Calculates variance as (L2 recoveries / L1 rejections) * 100
  • Triggers alert if variance > 30%
  • Calculates hourly throughput automatically
  • Triggers alert if throughput < 10 preleads/hour for 2+ hours
  • Sends email notification to manager with context
  • Updates real-time dashboard with alert count
  • Stores historical alerts for reporting
  • Escalates to senior management after 3 consecutive days above threshold

See Also

← Back to Use Cases