# 12. Managing Leads in an Affiliate Hub

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

This section explains how leads behave inside an affiliate hub and how to work with them efficiently.

##### What Is a Lead in an Affiliate Hub?

A lead in an affiliate hub 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 Affiliate Hub label
4. Tracked using the Affiliate ID (if configured)

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

##### Viewing Leads in an Affiliate Hub

To view leads:

1. Go to Affiliate Hub in the left sidebar.
2. Click on the desired affiliate hub from the list.
3. Open the **Leads** tab (or Leads section inside the affiliate hub 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:** `<span class="language-xml"><span class="hljs-tag"><<span class="hljs-name">firstName</span></span></span>> <span class="hljs-tag"><<span class="hljs-name">lastName</span></span>>`

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 an affiliate hub 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 Affiliate Hubs

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 affiliate hub 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 affiliate hub 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 affiliate hub.
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.

**Hub-Level Persistence** The state of quick toggles is automatically saved for each affiliate hub separately.

<span style="color: rgb(187, 187, 187); font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Oxygen, Ubuntu, Roboto, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif; font-size: 1.4em; font-weight: 400;">Only FTD (Fast Toggle)</span>

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 affiliate hub.  
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
    
    Affiliate hub 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 affiliate hub history for audit and reporting purposes.

##### FTD Detection and First Transaction Date

The system determines FTD (First Time Deposit) status based on the client’s transaction history.

**How FTD Is Calculated** A lead becomes marked as FTD when:

1. The associated client completes their first successful deposit transaction.
2. The transaction status is completed/approved.
3. The transaction meets the system’s deposit criteria (as defined in the Core Banking module).

The system reuses the same FTD logic used in Analytics and CRM reporting. No separate FTD calculation is introduced at the affiliate hub level.

**First Transaction Date** When a client completes their first valid deposit:

1. The FTD column in the Leads table is populated with the date and time of that first transaction.
2. This value reflects the earliest completed deposit in the client’s transaction history.

> **Important:**
> 
> If a client already existed in the system before entering the affiliate hub and had prior transactions:  
> The FTD date will reflect the true first transaction in the system.  
> It will not be recalculated based on affiliate hub registration date.

**Known Update Requirement** If the First Transaction Date is not appearing correctly:

Possible causes may include:

1. Transaction was not marked as completed.
2. Deposit type does not match FTD criteria.
3. Historical transaction exists but was not indexed.
4. Data sync delay between Core Banking and CRM modules.

FTD status and first transaction date are always derived from the Transactions module, not manually editable in the Affiliate Hub view.

##### Operational Best Practices

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

Regular affiliate hub monitoring ensures:

1. Clean client data
2. Accurate marketing attribution
3. Proper onboarding routing
4. Reduced compliance risks

> **Important Notes**
> 
> Editing an affiliate hub does not retroactively change already processed leads.  
> Duplicate logic is centralized and cannot be modified at the affiliate hub level.  
> Affiliate hubs control routing at intake stage only; client lifecycle management happens in the Clients module.  
> Deactivating an affiliate hub prevents new leads from entering but does not remove historical data.