🎯Leads Manager

The Leads Manager is a CRM-style module for collecting, organizing, and acting on leads from any source. It features a Kanban pipeline board, webhook ingestion, dynamic custom fields, and direct broadcast messaging.

---

Table of Contents

• Accessing the Leads Manager

• Kanban Board

• Creating Leads

• Lead Details

• Custom Fields

• Pipeline Configuration

• Webhooks

• Automations

• Broadcasting to Leads

• Converting Leads to Contacts

• API Reference

---

Accessing the Leads Manager

Navigate to Leads in the sidebar. Requires the leads:view permission (available to Admin, Super Admin, and Marketer roles by default).

The first time you access the Leads page, a default pipeline with 6 stages is automatically created for your workspace.

---

Kanban Board

Leads are displayed as cards organized into columns, where each column represents a pipeline stage.

Moving leads between stages

Drag and drop a lead card from one column to another. The stage change is saved immediately and logged in the lead's activity timeline.

Searching and filtering

Use the search bar to filter leads by name, email, phone, or company. Use the source dropdown to filter by how the lead was created (Manual, Webhook, Import, API).

---

Creating Leads

Manually

Click Add Lead in the top-right corner. Fill in:

Field	Required	Description
Name	Yes	Full name of the lead
Email	No	Email address
Phone	No	Phone number (include country code for SMS/WhatsApp)
Company	No	Company name
Title	No	Job title or position
Tags	No	Comma-separated tags (e.g. hot, referral, enterprise)

The lead is placed in the first stage of the active pipeline.

Via Webhook

See the Webhooks section below.

Via API

POST /v1/leads
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Jane Smith",
  "email": "[email protected]",
  "phone": "[phone]",
  "company": "Acme Corp",
  "title": "VP Marketing",
  "source": "api",
  "score": 75,
  "tags": ["enterprise", "inbound"],
  "customFields": {
    "planInterest": "Enterprise",
    "annualRevenue": 5000000,
    "_displayNames": {
      "planInterest": "Plan Interest",
      "annualRevenue": "Annual Revenue"
    }
  }
}

---

Lead Details

Click any lead card to open the detail drawer. The drawer shows:

• Lead Information - Name, email, phone, company, title, current stage, source, score

• Custom Fields - All key:value pairs sent via webhook or API, displayed with their human-readable names

• Notes - Internal notes with author and timestamp. Add notes from the text area at the top of the section

• Activity Timeline - Chronological log of all actions: stage changes, assignments, notes, field updates, conversions

• Tags - Visual tag badges

---

Custom Fields

Custom fields allow you to store any additional data with a lead. They follow the same pattern used in Contacts.

How it works

Custom fields are stored as JSON key:value pairs. Each field has:

• A camelCase key used internally (e.g. annualRevenue)

• A display name shown in the UI (e.g. Annual Revenue)

Display names are stored in a special _displayNames metadata object within the custom fields.

Example structure

{
  "planInterest": "Enterprise",
  "annualRevenue": 5000000,
  "referralSource": "Partner Program",
  "_displayNames": {
    "planInterest": "Plan Interest",
    "annualRevenue": "Annual Revenue",
    "referralSource": "Referral Source"
  }
}

When leads arrive via webhook, unmapped fields are automatically converted to custom fields. The original field name from the webhook payload is preserved as the display name.

---

Pipeline Configuration

Click the gear icon in the header to open Pipeline Settings.

Default stages

Stage	Color	Type	Description
New	Blue	Open	Freshly created leads
Contacted	Amber	Open	Initial outreach made
Qualified	Purple	Open	Lead meets qualification criteria
Proposal	Pink	Open	Proposal or offer sent
Won	Green	Won	Successfully converted
Lost	Red	Lost	Did not convert

Customizing stages

• Rename any stage by editing the name field

• Reorder stages using the up/down arrows

• Change colors using the color picker

• Set type to Open, Won, or Lost (affects reporting)

• Add new stages with the "Add Stage" button

• Remove stages (minimum 2 required)

Click Save to apply changes. Existing leads remain in their current stage.

---

Webhooks

Webhooks let you receive leads from any external source: landing pages, forms, CRMs, ad platforms, Zapier, Make, or any system that can send HTTP POST requests.

Setting up a webhook

1. Click Webhooks in the leads page header

2. Enter a name (e.g. "Landing Page Form") and click Create

3. Copy the generated webhook URL

The URL format is:

https://your-api-domain/v1/webhooks/leads/{apiKey}

Sending data to the webhook

Send a POST request with a JSON body to the webhook URL. No authentication headers are needed - the API key in the URL acts as authentication.

curl -X POST https://your-api-domain/v1/webhooks/leads/abc123-def456 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "[phone]",
    "company": "Widgets Inc",
    "job_title": "CTO",
    "utm_source": "google",
    "utm_campaign": "spring_2024",
    "form_page": "/pricing",
    "budget": "$50k-100k"
  }'

Response:

{
  "received": true,
  "leadId": "uuid-of-created-lead"
}

Field mapping

The webhook processor maps incoming JSON fields to lead properties:

Incoming field	Maps to	Notes
name	Lead name	Required. Falls back to email, phone, or webhook name
email	Lead email
phone	Lead phone
company	Lead company
title	Lead title
Everything else	Custom fields	Stored as key:value with auto-generated display names

In the example above, job_title, utm_source, utm_campaign, form_page, and budget would all be stored as custom fields with their original names preserved as display names.

Custom field mapping

You can configure custom field mappings per webhook to route incoming fields to specific lead properties. For example, map job_title to the title core field instead of storing it as a custom field.

Nested payloads

Nested JSON objects are automatically flattened. For example:

{
  "contact": {
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "metadata": {
    "source": "facebook"
  }
}

Produces custom fields: contact.first_name, contact.last_name, metadata.source.

Managing webhooks

• Regenerate key - Creates a new API key (old URL stops working immediately)

• Delete - Removes the webhook. Previously received leads are not affected

• Stats - Each webhook shows total leads received and last received timestamp

---

Automations

Automations let you define "If/Then" rules that automatically send messages (WhatsApp, SMS, or Email) when a new lead arrives via a webhook. Each automation runs a waterfall of steps with optional delay between steps and fallback channels if a message fails.

Creating an automation

1. Click Automations in the leads page header

2. Click New to open the Rule Builder

3. Fill in the automation settings:

Field	Required	Description
Automation Name	Yes	A descriptive name (e.g. "Welcome Sequence")
Description	No	What this automation does
Trigger on Webhook	Yes	Which webhook source triggers this automation
Safety Lock	No	Dedup window to prevent the same lead from triggering the automation twice (default: 5 minutes)
Active toggle	No	Enable or disable the automation (default: active)

Adding steps

Each automation has one or more steps executed in order. For each step, configure:

Setting	Description
Channel	WhatsApp, SMS, or Email
Delay	How long to wait before sending: Immediate, 5 min, 15 min, 30 min, 1 hour, 2 hours, or 24 hours
Template	An approved message template for the selected channel
Fallback	Optional. If the step fails, automatically retry on a different channel (e.g. if WhatsApp fails, fall back to SMS)

Click Add Step to add more steps to the waterfall. Steps run in order from top to bottom.

Example: Welcome sequence with fallback

1. Step 1 - WhatsApp, Immediate, "Welcome_Template" with fallback to SMS

2. Step 2 - Email, 2 hours delay, "Follow_Up_Email"

When a lead arrives via the selected webhook:

• A WhatsApp message is sent immediately using the Welcome template

• If WhatsApp fails (e.g. lead doesn't have WhatsApp), the system automatically falls back to SMS

• 2 hours later, a follow-up email is sent

How the safety lock works

The safety lock prevents the same lead from triggering the automation multiple times within a set window. This is useful when the same webhook might fire multiple times for the same person (e.g. duplicate form submissions).

If a lead with the same phone or email arrives within the safety lock window, the automation is skipped and a "Safety lock" event is logged in the lead's activity timeline.

Managing automations

From the Automations list modal, you can:

• Toggle active/inactive - Pause or resume an automation without deleting it

• View stats - See how many times the automation was triggered, completed, and failed

• Edit - Modify steps, name, webhook source, or safety lock settings

• Delete - Remove the automation permanently

Automation activity timeline

Every automation action is logged in the lead's activity timeline in the Lead Detail view:

Event	Icon	Description
Automation triggered	bolt	The automation started for this lead
Step sent	check	A message was sent successfully
Step failed	error	A message failed to send (with error details)
Fallback	swap	The system fell back to an alternative channel
Automation completed	task	All steps finished
Automation skipped	block	The automation was skipped (safety lock or missing contact info)

For sent messages, the timeline also shows delivery status (Sent, Delivered, Read, or Failed) which updates automatically as status webhooks arrive from the messaging platform.

If a step fails, a Retry button appears in the timeline so you can manually re-attempt the failed step.

Message tracking

Automation messages use the same tracking infrastructure as Broadcast Campaigns. Each message sent by an automation creates a Broadcast Message record with:

• Delivery status (Pending, Sent, Delivered, Read, Failed)

• Error codes and messages for failures

• Timestamps for each status change

This means automation messages appear in your existing broadcast analytics and reports — there are no separate reporting tables.

---

Broadcasting to Leads

Quick Send

Select leads and send a direct message via SMS, WhatsApp, or Email.

1. Open a lead's detail drawer or use bulk selection

2. Click Quick Send

3. Choose a channel (SMS, WhatsApp, Email)

4. Compose your message

5. Click Send

Requires the lead to have the appropriate contact info (phone for SMS/WhatsApp, email for Email).

Full Broadcast Campaign

For larger campaigns with templates, tracking, and analytics:

1. Select leads on the Kanban board

2. Click Create Broadcast Audience to export selected leads as a broadcast audience

3. Navigate to Broadcast > Campaigns to create a full campaign using the exported audience

This leverages the existing broadcast infrastructure with template management, variable mapping, delivery tracking, and analytics.

---

Converting Leads to Contacts

When a lead becomes a customer, convert them to a contact:

1. Open the lead's detail drawer

2. Click Convert

3. Enter a contact name (pre-filled from the lead) and optionally choose a platform

4. Click Confirm

The Convert button disappears immediately after clicking Confirm — you don't need to reload the page.

What happens during conversion

• If a contact with the same phone number or email already exists in your workspace, the lead is linked to that existing contact instead of creating a duplicate.

• If you accidentally click Convert more than once (e.g. double-click), the system safely returns the same contact — no duplicates are created.

• The lead's name, email, phone, custom fields, and notes are carried over to the new contact.

• The lead is marked as converted with a timestamp and a link to the contact record.

• A "Converted" event is logged in the lead's activity timeline.

---

API Reference

Endpoints use service-specific prefixes (e.g. /v1/identity/leads, /v1/identity/lead-pipelines, /v1/identity/lead-webhooks, /v1/identity/lead-automations) and require a Bearer token (except the webhook ingest endpoint).

Leads

| Method | Endpoint | Description | | -------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | ------------------------------------------------------------------------- | | GET | /leads | List leads. Query params: search, stageId, pipelineId, source, assignedTo, tag, page, limit, sortBy, sortOrder | | GET | /leads/:id | Get lead with activity log | | POST | /leads | Create lead | | PATCH | /leads/:id | Update lead fields | | DELETE | /leads/:id | Soft delete lead | | PATCH | /leads/:id/stage | Move lead to stage. Body: { "stageId": "uuid" } | | PATCH | /leads/:id/assign | Assign lead. Body: { "assignedTo": "userId" } | | POST | /leads/:id/convert | Convert lead to contact | | POST | /leads/:id/notes | Add note. Body: { "value": "Note text" } | | POST | /leads/bulk-action | Bulk action. Body: { "action": "move_stage | assign | delete | tag", "leadIds": [...], "stageId?": "", "assignedTo?": "", "tags?": [] } |

Pipelines

Method	Endpoint	Description
GET	/lead-pipelines	List pipelines with stages
POST	/lead-pipelines	Create pipeline with stages
PATCH	/lead-pipelines/:id	Update pipeline and stages
DELETE	/lead-pipelines/:id	Delete pipeline (not default)
POST	/lead-pipelines/ensure-default	Create default pipeline if none exists

Webhooks

Method	Endpoint	Description
GET	/lead-webhooks	List webhook configs
POST	/lead-webhooks	Create webhook
PATCH	/lead-webhooks/:id	Update webhook config
DELETE	/lead-webhooks/:id	Delete webhook
POST	/lead-webhooks/:id/regenerate-key	Regenerate API key

Webhook Ingest (Public - no auth required)

Method	Endpoint	Description
POST	/webhooks/leads/:apiKey	Receive lead from external source

Automations

Method	Endpoint	Description
GET	/lead-automations	List all automation workflows
GET	/lead-automations/:id	Get automation workflow details
POST	/lead-automations	Create automation workflow. Body: { "name": "...", "webhookSourceId": "uuid", "steps": [...], "safetyLockMinutes": 5 }
PATCH	/lead-automations/:id	Update automation workflow
DELETE	/lead-automations/:id	Delete automation workflow
POST	/lead-automations/:id/retry/:leadId	Retry the last failed automation step for a lead
GET	/leads/:id/automation-timeline	Get automation events and delivery status for a lead

Broadcast Bridge

Method	Endpoint	Description
POST	/leads/broadcast/quick-send	Send message to selected leads
POST	/leads/broadcast/create-audience	Export leads as broadcast audience

---

Permissions

Permission	Description	Default Roles
leads:view	View leads page and data	Admin, Super Admin, Marketer
leads:manage	Create, edit, delete leads and configure pipelines/webhooks	Admin, Super Admin, Marketer

---

Database Tables

Table	Description
leads	Core lead records with custom fields
lead_pipelines	Pipeline definitions per workspace
lead_pipeline_stages	Stages within pipelines
lead_webhooks	Webhook endpoint configurations
lead_activities	Audit log of all lead actions
lead_automation_workflows	Automation rule definitions with steps