Lead Lifecycle

A lead represents a person in the system. When a lead is submitted, it goes through a multi-step processing pipeline that evaluates, qualifies, and delivers it to the appropriate campaign endpoint.

Entry Points

Leads enter LeadSail through three paths:

• API Submission — External systems submit leads via POST /api/v1/leads/submit with contact data and a target campaign ID
• CSV Import — Bulk import leads from a CSV file through the import wizard
• Manual Create — Add a single lead from the Leads page using the Add Lead button (requires campaign, name, email, and phone)

API-submitted and manually-created leads are processed through the qualification engine immediately. Imported leads are created with a new status and are not automatically processed.

Lead vs. Submission

LeadSail separates person-level data from delivery-attempt data:

• Lead — The person record. Contains contact info, questionnaire answers, notes, attribution, compliance data, and flags. One lead exists per person.
• Submission — A single delivery attempt. Contains the campaign snapshot, qualification result, routing decisions, posting result, and journey events. One lead can have multiple submissions (original + reposts).

This separation means a lead's contact info stays consistent even when reposted to different campaigns.

Processing Pipeline

When a lead is submitted via the API, the qualification engine processes it through these steps in order:

1. Routing Rules — Evaluate which campaigns match the lead's data based on configured conditions (e.g., state, age, questionnaire answers)
2. First Submission Actions — If the matched campaign has a pre-delivery action (voice AI, SMS, human review, webhook), the lead pauses at pending_action until the action completes
3. Disqualification Conditionals — Check for hard disqualification conditions (e.g., excluded states, age ranges)
4. Dynamic Keys — Apply field transformations and computed values before delivery
5. Required Fields — Verify all fields required by the delivery endpoint are present
6. Field Qualification — AI-powered validation of individual field values against endpoint requirements
7. Payload Building — Construct the delivery payload using the endpoint's field configuration
8. Delivery — Send the payload to the campaign's delivery endpoint(s)
9. Fallback — If delivery fails or the lead is rejected, try configured fallback campaigns

Status Flow

A typical lead progresses through statuses like this:

new/pending → processing → qualified → delivered → accepted

With first submission actions:

pending → processing → pending_action → [voice/sms interaction] → qualified → delivered

With fallback:

pending → processing → qualified → failed → [fallback] → delivered

See Lead Statuses for the complete status reference.

Deduplication

When a lead is submitted, LeadSail checks for existing leads with the same email or phone number. If a match is found:

• The lead is flagged with isDuplicate: true
• The duplicate status may be set depending on campaign configuration
• Deduplication is checked within the campaign scope

Reposting

A lead can be reposted to a different campaign after its initial submission. Reposting creates a new submission under the same lead record. The lead tracks all campaigns it has been submitted to in the repostedTo array.

Reposting can be triggered:

• Manually — From the lead detail page via the Repost action
• Automatically — Via fallback campaign configuration when initial delivery fails
• Via API — Using the POST /api/v1/leads/{leadId}/repost endpoint