📋 Lead Generation & Management — V2 Guide

Overview

RubiPro's flagship inbound + outbound lead module. The inbound side gives you an embeddable form widget — paste one snippet on your website (or your customer's website if you're an agency) and submissions appear in your CRM as leads. The outbound side gives you a CSV import wizard for bulk-loading leads from external sources, plus an agent workspace where agents work the queue, log dispositions, schedule callbacks, and convert qualified leads to customers.

V2 activates the dead schema pieces that V1 created but never engineered: lead scoring rules now compute quality_score (0-100) on every submission, duplicate detection flags incoming leads against existing tenant data, NotificationEngine fires for new-lead alerts, PHPMailer sends auto-replies + notify emails, WebhookManager dispatches lead.* events for external integrations.

The lead pipeline

What's new in V2

Embedding the form

After building a form in Tenant Admin → Lead Forms, click Embed to copy the snippet:

<div id="rubi-lead-form" data-form-uuid="YOUR-FORM-UUID-HERE"></div>
<script src="https://rubiprofessional.com/js/lead-widget.js?v=3"></script>

Paste it into your website's HTML wherever you want the form. The widget loads asynchronously, doesn't block page render, and styles itself with sensible defaults. Multiple forms on the same page work — each div's data-form-uuid identifies which form to render.

Click Preview on a form to see exactly what customers will see. The preview page loads the same widget against a real production endpoint — submissions in preview ARE recorded as leads, so test with sandbox data.

Lead scoring

Tenant Admin → Lead Scoring Rules. Create rules with:

• Type: field_match (most common — match a form field), behavior, source, engagement.
• Field: any submitted form field (email, phone, company, utm_source, utm_campaign, utm_medium, utm_term, utm_content, etc.) plus extracted standards (first_name, last_name).
• Operator: equals, contains, starts_with, ends_with, greater_than, less_than, in_list (comma-separated), not_in_list.
• Match value: what to compare against (case-insensitive for text operators).
• Points: positive or negative integer.
• Max points (optional): cap on this rule's contribution.

Examples:

• "Enterprise email" — field=email, operator=ends_with, value=".com", points=+10, max=10
• "Free email penalty" — field=email, operator=in_list, value="gmail.com,yahoo.com,hotmail.com", points=-5
• "Has phone" — field=phone, operator=starts_with, value="", points=+15 (any non-empty phone)
• "Paid traffic" — field=utm_source, operator=in_list, value="google,facebook,linkedin", points=+20
• "Has company" — field=company, operator=starts_with, value="", points=+15

The Test sandbox lets you paste sample lead JSON and see the resulting score before committing the rule live. Score is clamped 0-100 — negative totals floor at 0.

Duplicate detection

On every web submission, V2 checks the incoming email + phone against three sources within the current tenant:

• web_leads — open leads (status NOT IN spam/rejected/duplicate)
• lead_records — open list records (status NOT IN converted/dnc/bad_number)
• customers — already-converted

Match conditions: email is case-insensitive exact-match. Phone is normalized to last-10-digits (strip non-digits, take last 10). If either matches, the new lead is inserted with status='duplicate' and duplicate_of pointing to the matched lead. Agents see the duplicate flag in the workspace and decide whether to merge, dismiss, or escalate.

For CSV imports, the import wizard's duplicate_action setting controls behavior per-row: skip (don't import), merge (update existing record), keep_both (insert anyway, no flag). All matching is tenant-scoped.

Notifications + webhooks

When a non-spam lead lands, V2 fires three notification channels and one webhook channel — all best-effort, none block submission:

• In-app: NotificationEngine sends to every user_id in the form's notify_users JSON array. Notification has a deep link to the lead in the CRM.
• Email to admin: the form's notify_email field gets a plain-text alert with full lead details + link to CRM.
• Auto-reply to lead: if auto_reply_enabled and the lead provided an email, PHPMailer sends the configured subject/body with token replacement: {{first_name}}, {{last_name}}, {{email}}, {{phone}}, {{company}}, {{form_name}}.
• Webhook: WebhookManager dispatches lead.created with payload {lead_id, form_id, form_name, first_name, last_name, email, phone, company, status, quality_score, utm_*, created_at, extras}. Subscribers configure their endpoints in Tenant Admin → Webhooks.

Other lifecycle events with webhook dispatch: lead.converted (lead → customer), lead.qualified, lead.rejected, lead.assigned, lead.disposition_recorded.

Agent workspace

Agents open Leads in the CRM. Four sub-tabs:

• My Queue — leads currently assigned to me, sorted overdue-callbacks-first. CSV export available.
• Callbacks — three groupings: overdue, today, upcoming.
• Get Lead — pulls the next available lead from the tenant pool. Three-tier priority: overdue callbacks for me → leads assigned to me → unassigned cherry-pick or round-robin per the lead list's distribution_mode.
• Search — full-text across leads + lead_records by name / email / phone / company.

Per-lead actions: log disposition (with required-notes / required-callback enforcement per the disposition_code config), schedule callback, add note, unlock (release back to the pool), assign to another agent, convert to customer.

Conversion preserves: notes (with "[From Lead]" prefix), custom fields (mapped per the lead list's column_mapping), source attribution, and writes a creation note on the customer with the lead source.

CSV bulk import

Tenant Admin → Lead Lists → Import. 4-step wizard:

1. Upload + name. Pick a CSV, name the list, set list_type (outbound / callback / priority).
2. Map columns. Preview the first 10 rows, drag CSV headers to standard fields (first_name, last_name, email, phone, address, city, state, zip, notes) plus any custom fields you've configured.
3. Settings. Priority, max attempts before retire, distribution_mode (cherry_pick / round_robin / manual), default agent assignment, duplicate action (skip / merge / keep_both).
4. Confirm. Run the import. Each row passes through duplicate detection, lands in lead_records (or skips per duplicate_action), and the list is ready for agents.

Imports run synchronously in the request handler — large files (10k+ rows) may take a few seconds. Future versions will queue large imports for background processing.

Spam protection

Five layers, scored 0-1.0. Spam_score ≥ 0.7 → status='spam' (still recorded for audit, never delivered to agent inbox):

• Honeypot — invisible field bots fill in. +0.6 spam score if triggered.
• Submission timing — minimum seconds from page load to submit (default 3, configurable). +0.4 if too fast.
• Keyword blocklist — JSON array of flagged keywords. +0.3 if found in any field.
• Domain blocklist — JSON array of blocked email domains. +0.5 if email matches.
• IP rate limiting — max submissions per IP per 24 hours (default 10, configurable per form). Hard-block at the limit.

Repeat-offender IPs can be added to lead_spam_ips with optional expiration. Submissions from blocked IPs are silently accepted but never recorded — the bot doesn't get feedback that it's blocked.

API + integrations

Public submission

POST /api/lead-capture.php
Content-Type: application/json

{
  "form_uuid": "abc-123-...",
  "form_data": { "first_name": "...", "email": "...", "phone": "...", ... },
  "submission_time": 7,                            // seconds from page load
  "source_url": "https://example.com/contact",
  "utm_source": "google", "utm_medium": "cpc", ...
}

Mac-app v2 endpoints (preserved verbatim)

GET  /api/v2/leads.php             → list leads
GET  /api/v2/leads.php?id=123       → one lead
POST /api/v2/leads.php/submit       → public submission
POST /api/v2/leads.php/convert/123  → convert lead → customer
PUT  /api/v2/leads.php/leads/123    → update lead
GET  /api/v2/leads.php?segments=forms     → list forms

Webhook subscribers

Configure outbound webhooks in Tenant Admin → Webhooks. Subscribe to events: lead.created, lead.converted, lead.qualified, lead.rejected, lead.assigned, lead.disposition_recorded.

Frequently asked questions