12. Managing Leads in a Bucket

Once a bucket is created and connected to a project, it becomes an active entry point for incoming leads. Managing leads inside a bucket allows you to monitor registrations, track processing status, identify duplicates, and ensure proper routing into your CRM.

This section explains how leads behave inside a bucket and how to work with them efficiently.

What Is a Lead in a Bucket?

A lead in a bucket represents a new client registration that entered the system through a specific acquisition channel (e.g., affiliate, campaign, API, landing page).

Each lead is automatically:

1. Linked to a specific Project

2. Assigned to a Manager

3. Tagged with the Bucket label

4. Tracked using the Affiliate ID (if configured)

Buckets act as controlled intake queues before clients become fully processed CRM records.

Viewing Leads in a Bucket

To view leads:

1. Go to Buckets in the left sidebar.

2. Click on the desired bucket from the list.

3. Open the Leads tab (or Leads section inside the bucket view).

You will see a table containing:

1. Client name / email

2. Registration date

3. Processing status

4. Duplicate status (if applicable)

5. Project and manager

6. Source tracking details

The table supports sorting and filtering (depending on system configuration).

Leads Table: Full Name Column, Sorting, and Name Filters

To improve usability and allow faster identification of leads, the Leads table includes a dedicated Full name column with sorting and filtering capabilities.

Full Name Column
A new column titled Full name is displayed in the Leads table.

Column position: Immediately after the ID column.

Value format: <firstName> <lastName>

Behavior:

1. If both first and last name exist → displayed as “FirstName LastName”.
2. If only first name exists → displayed as “FirstName”.
3. If only last name exists → displayed as “LastName”.
4. If both are missing → the cell remains empty.

The column uses the same first and last name fields already stored for the lead. No additional data sources are introduced.

Sorting by Full Name
The Full name column supports sorting.

Sorting behavior:
Follows the standard table sorting mechanism (ASC / DESC).

Sorting priority:
Primary: first name
Secondary: last name

Sorting integrates with:

1. Pagination
2. Existing filters
3. Other active sorting parameters

No custom sorting logic is introduced outside of the established table architecture.

Filtering by First and Last Name
Two separate filters are available in the Leads filter set:

First Name Filter
Filters leads by first name only.
Uses the same string matching logic applied elsewhere in the system (contains / startsWith / exact — depending on system convention).

Last Name Filter
Filters leads by last name only.
Uses the same matching behavior as the First Name filter.

Combined Filtering
Both filters can be used together.

Behavior:
Filters apply using AND logic.

Example:
First name = “John”
Last name = “Smith”
→ Returns only leads matching both criteria.

The filters work correctly with:
Pagination
Sorting
Other active filters
The “Only unassigned leads” toggle

Performance and Stability
The addition of the Full name column:

1. Does not modify existing columns

2. Does not affect lead processing, assignment, or reprocessing flows

3. Does not introduce UI regressions

4. Uses the existing table rendering, filtering, and sorting mechanisms

Lead Statuses

Leads inside a bucket typically move through defined processing states:

New
The lead has entered the system but has not yet been processed.

Processed
The lead has successfully passed validation and has been created or merged as a client.

Duplicate
The system detected an existing client matching duplicate detection rules.

Rejected / Invalid
The lead did not meet validation criteria.

Status is automatically assigned by the system during processing.

Duplicate Handling in Buckets

If a lead is detected as a duplicate:

1. The system links it to the existing client record.

2. The client’s Last duplicate date field is updated automatically.

3. The lead status reflects Duplicate.

This ensures:

1. No duplicate CRM records are created.

2. Duplicate activity is traceable over time.

3. Managers can monitor data quality trends.

Duplicate detection logic is system-driven and cannot be manually overridden inside the bucket view.

Reprocessing Leads

In certain cases (e.g., configuration changes or temporary API errors), you may need to reprocess a lead.

If the system allows reprocessing:

1. Select the lead from the list.

2. Click the action menu (three-dot menu).

3. Choose Reprocess.

Reprocessing will:

1. Re-run duplicate checks

2. Re-apply routing logic

3. Attempt client creation again

Note: Reprocessing does not bypass duplicate detection rules.

Filtering and Searching Leads

Within the bucket Leads view, you can typically:

1. Search by email, ID, or name

2. Filter by registration date

3. Filter by status (New, Processed, Duplicate)

4. Filter by manager or project (if supported)

This helps you:

1. Monitor daily acquisition flow

2. Identify spikes in duplicate registrations

3. Prioritize unresolved or failed leads

4. Analyze campaign-level performance

Only Unassigned Leads (Fast Toggle)

To quickly focus on leads that are not yet assigned to a manager, use the Only unassigned leads toggle located above the leads table.

How it works

1. Disabled (default) — Displays all leads in the selected bucket.

2. Enabled — Displays only leads that do not have an assigned manager.

The definition of “unassigned” follows the system’s backend assignment logic and uses the same criteria as the existing routing model.

Location
The toggle is placed:

1. Above the leads table

2. Next to the Search field

3. Outside of the Filters drawer

This control is designed for fast operational access and is not part of advanced filtering.

Per-Bucket Persistence
The state of quick toggles is automatically saved for each bucket separately.

Stored under:
localStorage → BUCKETS_FILTERS

Structure:

{
"<bucketId>": {
"onlyUnassignedLeads": true,
"onlyFTDLeads": true
}
}

Behavior:

If no saved state exists:
onlyUnassignedLeads = false
onlyFTDLeads = false

Each bucket maintains its own toggle state independently.

Only FTD (Fast Toggle)

To quickly focus on converted leads, use the Only FTD toggle located above the leads table.

How it works
Disabled (default) — Displays all leads in the selected bucket.
Enabled — Displays only leads that meet the system definition of FTD (First Time Deposit).

The toggle reuses the existing FTD flag and business logic already used in CRM and analytics. No separate FTD calculation is introduced.

Combined Behavior with Other Toggles
The Only FTD toggle works independently from the Only unassigned leads toggle.
If both are enabled:
The system displays only leads that are:
FTD
AND
Unassigned

Standard filter intersection logic applies.

How Leads Become Clients

When a lead is successfully processed:

1. A client record is created in the Clients module

2. The client inherits:
   Project

   Manager

   Bucket label

   Affiliate ID (if configured)

    

3. Action timeline tracking begins

4. The client becomes visible in all CRM modules

After processing, the lead remains part of the bucket history for audit and reporting purposes.

Operational Best Practices

Review New leads daily
Monitor Duplicate leads weekly
Investigate abnormal duplicate spikes
Keep Affiliate IDs accurate for tracking
Deactivate unused buckets to prevent routing errors

Regular bucket monitoring ensures:

1. Clean client data

2. Accurate marketing attribution

3. Proper onboarding routing

4. Reduced compliance risks

Important Notes

Editing a bucket does not retroactively change already processed leads.
Duplicate logic is centralized and cannot be modified at the bucket level.
Buckets control routing at intake stage only; client lifecycle management happens in the Clients module.
Deactivating a bucket prevents new leads from entering but does not remove historical data.