Leads — Reference
The Leads surface is the capture-and-qualification plane for every SGEN site. It owns every inbound form submission that the business wants to track as a potential opportunity — the original payload, the scoring outcome, the qualification workflow, the assignment to a staff member, and the conversion outcome when the lead graduates into a customer relationship. Anything that arrives as raw interest and needs to be triaged before becoming a contact traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping a lead-qualification workflow. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Leads live under the Leads module in SG-Admin. The module renders four primary views — the lead inbox (new, unassigned), the pipeline kanban (by status), the per-lead detail view (capture payload + score + activity), and the assignment workspace — and exposes a small set of write operations for create, qualify, assign, score-override, status transition, conversion, and disqualification.
The module is paired by convention: one half renders the views and prepares the data, the other half handles writes and returns AJAX responses. Engineers reading the SG-Admin source will see this split across two controller files; the reference below describes the combined surface as it appears to a calling integration.
Leads and Contacts are distinct surfaces and should not be confused. A lead is a capture record — short-lived, unqualified, scored, assigned for follow-up — and exits the surface when it converts (graduating into a contact) or is disqualified (retained for audit). A contact is the durable relationship record on the other side of conversion. Every converted lead becomes a contact; not every contact was once a lead.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Leads
- URL prefix:
/sg-admin/leads/ - View templates:
application/views/Admin/Leads/
┌────────────────────────────────────────────────────────────────────────────┐│ SG-Admin → Leads → Inbox (12) [Filter: New ▾] │├────────────────────────────────────────────────────────────────────────────┤│ Source Captured Score Status Assigned to ││ ────────────────── ───────────── ────── ─────────── ──────────────── ││ Pricing form 2 min ago 87 ★ new — (unassigned) ││ Demo request form 14 min ago 92 ★ contacted Sarah Kim ││ Newsletter signup 1 hr ago 34 new — (unassigned) ││ Contact us form 2 hr ago 71 ★ qualified Marcus Tan ││ Pricing form 3 hr ago 18 disqualified — (auto) ││ ││ [⋯ Open] [⋯ Assign] [⋯ Qualify] [⋯ Convert to contact] [⋯ Disqualify] │└────────────────────────────────────────────────────────────────────────────┘Actions
The Leads surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List and filter
Returns the lead records visible to the current operator, paginated, with source, captured, score, status, and assigned-to columns. Supports column sort, free-text filter across the captured payload, status filter (new / contacted / qualified / converted / disqualified), score range, source filter (which form or import the lead came from), assignment filter, and per-page count. The default view scopes to the inbox (status = new, unassigned) so fresh leads surface first.
Create lead (form submission)
Form submissions on the public site create lead records automatically when the form's submission target is set to Leads. The captured payload is stored as-is in the payload field; the surface extracts a small set of canonical fields (email, name, source) from the payload at capture time. The lead enters with status = new and a score from the configured scoring rules.
Create lead (manual)
Opens an empty lead form. Required fields: source (free-text or chosen from the configured source catalog), at least one contact field (email or phone). Optional fields cover name, organization, role, payload (free-form), and an initial assigned-to. On submit, the surface persists the record and runs it through the same scoring pipeline as form submissions.
Score (automatic)
Every lead is scored at create time by the configured scoring rules. A score is an integer 0-100 derived from the payload — keyword matches in the message body, domain pattern of the email, source weight, and any custom rules configured per site. The score is set once at capture and is not auto-recomputed; operator overrides write a new score and stamp the override.
Score override
Adjusts a lead's score manually. Useful when the automatic score disagrees with operator judgment — a high-intent message scored low because the form was filled out clumsily, or a low-intent message scored high because keyword bait was hit. Overrides retain the original score in the audit log alongside the new value and the reason.
Assign
Attaches a staff member as the lead's owner. Assignment can be manual (operator picks a staff member from the dropdown) or rules-driven (round-robin, source-based routing, score-tier-based routing — all configured under Settings → Lead Assignment). Re-assignment is supported; the previous assignee is retained in the assignment history.
Status transition
Moves a lead through the qualification workflow. Default statuses: new → contacted → qualified → (converted | disqualified). Each transition writes a timestamp; the timeline view of a lead is built from this transition history. Custom statuses (a per-site configuration under Settings → Lead Pipeline) extend the default set.
Qualify
A specialized status transition. Moves a lead to qualified and surfaces a qualification form: discovery notes, fit assessment, next-step commitment. The qualification record is attached to the lead and visible in the per-lead detail timeline. Skipping the form (transitioning to qualified without it) is permitted but emits a lower-confidence flag on the lead.
Convert to contact
Graduates a lead into a Contact record. The operator chooses to attach to an existing contact (merge) or create a new contact (create-and-link). On submit, the surface writes the Contact record (or updates the existing one), sets the lead's status to converted, sets the lead's converted_to_contact_id to the surviving contact id, and copies the lead's tags and source into the contact's initial tag set. The lead remains in the system as an audit record of the original capture.
Disqualify
Marks a lead as disqualified with a required reason (chosen from the configured disqualification-reason catalog: spam, no-fit, wrong-audience, duplicate, no-response). Disqualified leads disappear from the default inbox view but remain queryable via the disqualified filter; they are retained for audit and for tuning the scoring rules.
Bulk action
Applies a single action (assign, status transition, disqualify, convert) to a checked set of leads in one request. The surface returns a per-row pass / fail report. Useful for clearing an inbox after a coordinated campaign drives a wave of low-quality submissions, or for assigning a fresh batch to a named staff member.
Data model
A lead record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. Stable across edits. |
source | string | Form slug, import batch, or manual. |
payload | json | The raw capture payload as posted. Preserved as-is. |
email | string | Extracted from payload at capture. Used for default de-duplication. |
name | string | Extracted from payload at capture. Optional. |
phone | string | Extracted from payload at capture. Optional. |
score | integer | 0-100. Set at capture by the scoring rules. |
score_override | integer | Set on manual override. Null if no override. |
status | enum | new, contacted, qualified, converted, disqualified (+ configured custom statuses). |
assigned_to | integer | Staff id of the current owner. Null when unassigned. |
qualification | json | Set on qualify — discovery notes, fit assessment, next-step. Null otherwise. |
disqualification_reason | string | Set on disqualify. Null otherwise. |
converted_to_contact_id | integer | Set on convert. Null otherwise. |
tags | array | Flat tag taxonomy. Copied to the contact on convert. |
captured_at | timestamp | Set on first submission, immutable. |
last_status_change_at | timestamp | Touched on every status transition. |
score_override; the original score is retained. Re-scoring (running the rules engine again over an existing payload, useful after rule changes) is a separate write path; it writes a new score and retains the prior values in the audit log.Conversion semantics. Conversion is one-directional. A lead converts into a contact; the contact does not convert back. The lead record remains in the system after conversion as the capture audit — what the visitor said, when, from which form, and what they scored. The contact record carries the ongoing relationship.
Assignment history. Every assign-to write captures the prior assignee in an append-only assignment-history table. The detail view surfaces the full history; reporting on assignment fairness, response time, and conversion rate uses this table.
Disqualified retention. Disqualified leads are retained, not deleted. They feed into the scoring-rules tuning loop (the classifier learns from operator decisions over time) and into the source-quality reporting (which forms produce the most disqualifications).
LEAD RECORD├── id integer primary key├── source string form slug or 'manual'├── payload json raw capture as posted├── email, name, phone extracted at capture├── score integer 0-100 (set by rules at capture)├── score_override integer manual adjustment (null if none)├── status enum new | contacted | qualified |│ converted | disqualified├── assigned_to integer current owner staff_id├── qualification json set on qualify (discovery notes)├── disqualification_reason string set on disqualify├── converted_to_contact_id integer set on convert (FK to Contacts)├── tags array copied to contact on convert├── captured_at timestamp immutable capture time└── last_status_change_at timestamp each transition↓ on convertCONTACT RECORD (Contacts surface)(new or merged; lead.tags + lead.sourceseed the contact's initial state)↓ on every assignASSIGNMENT HISTORY ROW(append-only, prior assignee retainedfor response-time + fairness reporting)↓ on every status transitionSTATUS TRANSITION ROW(timeline view source)Permissions
Access to the Leads surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Leads surface. (Form submissions that create leads from the public site enter through a separate public-form endpoint that does not require admin authentication; the capture path is gated by the form's own anti-abuse layer.)
Layer 2 — per-action capability. Within SG-Admin, each Leads action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| List leads | ✔ | ✔ | ✔ |
| Create lead (manual) | ✔ | ✔ | — |
| Edit lead | ✔ | ✔ | — |
| Score override | ✔ | ✔ | — |
| Assign | ✔ | ✔ | — |
| Re-assign (reassign owner) | ✔ | ✔ | — |
| Status transition (basic) | ✔ | ✔ | ✔ |
| Qualify (with form) | ✔ | ✔ | — |
| Convert to contact | ✔ | ✔ | — |
| Disqualify | ✔ | ✔ | — |
| Bulk action | ✔ | — | — |
| Configure scoring rules | ✔ | — | — |
| Configure assignment rules | ✔ | — | — |
Ownership rule. A lead carries an assigned owner. Operators with the edit-own-leads-only capability scope see and edit only leads where the owner matches them. The default roles above hold the broader scope; sales-team-style custom roles often narrow it. Unassigned leads are visible to operators with the inbox capability regardless of scope.
Conversion gate. Convert-to-contact requires both the Leads convert capability and the Contacts create capability. An operator who can qualify but cannot create contacts cannot complete the conversion — the surface routes the conversion through a separate confirmation step in that case, or surfaces a permission-mismatch message.
PII gate. Lead payloads carry PII by definition. Bulk export and bulk import of leads emit an Activity Log entry tagged leads.pii_movement for downstream review.
Audit. Every write — create, score override, assign, status transition, qualify, convert, disqualify, bulk action, scoring-rules edit, assignment-rules edit — emits an Activity Log entry. The log records the acting operator, the target lead, and the change shape. Conversion entries link both the source lead id and the destination contact id for downstream attribution reporting.
REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject│ (every /sg-admin/* call) │ (public form path is separate)└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-action) │└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Ownership scope │ edit-own-only role →│ │ filter to assigned owner└─────────────┬─────────────┘│ in scope▼┌───────────────────────────┐│ Conversion gate │ convert requires both│ │ leads.convert + contacts.create└─────────────┬─────────────┘│ passes▼┌───────────────────────────┐│ PII gate │ bulk import / export →│ │ leads.pii_movement tag└─────────────┬─────────────┘│ tagged▼action executes│▼Activity Log entry(conversion links source lead +destination contact for attribution)Related references
- Contacts — Reference. The destination of conversion. A converted lead writes (or merges into) a Contact record; the lead's tags and source seed the contact's initial state.
- Forms — Reference. The public-form surface that produces lead captures. Form submissions with submission target = Leads create lead records directly; the form's anti-abuse layer (rate limit, honeypot, captcha) is the only gate at capture.
- Staff — Reference. Lead owners attribute to staff records. Re-attribution applies on staff soft-delete; assignment-rule routing pulls from the active staff list.
- Settings — Reference. Owns the scoring-rules engine, the assignment-rules configuration, the source catalog, the disqualification-reason catalog, the lead-pipeline custom statuses, and Activity Log retention.
- Activity Log — Reference. Source of the leads audit trail. Every write emits an entry; the
leads.pii_movementtag is the bridge for downstream review. - Notifications — Reference. New-lead notifications, assignment notifications, and conversion notifications resolve through the notification template surface.
- Exports — Reference. The
leadssubject draws from this surface's data model. Bulk exports of leads raise the PII tag.
/docs/leads.