================================================================================
                    LEAD SOURCE REPORTING - DOCUMENTATION
================================================================================

LEAD AGGREGATION BY LOCATION
--------------------------------------------------------------------------------

Overview:
Leads are aggregated at the location level to provide accurate reporting across
all geographic regions. Each location (subaccount) maintains its own lead pool
while rolling up to the parent ROAR account for consolidated reporting.

Aggregation Rules:
1. Leads are assigned to locations based on the originating source
2. Each location can have multiple lead sources (web forms, phone, referrals)
3. Opportunities are fetched from GoHighLevel/EvolveCRM API per location
4. Date filtering uses lastStageChangeAt, then falls back to other date fields
5. Results are grouped by Contact Source field from each opportunity's contact

Location Hierarchy:
- ROAR Account (Parent Agency)
  └── Sub Account (Location/Subaccount)
      └── Lead Sources (Contact Source field)
          └── Opportunities (with status: open, won, lost, abandoned)


================================================================================
                         ROAR ACCOUNT SETTINGS
================================================================================

Account-Level Configuration:
-----------------------------
Setting                          | Description
---------------------------------|------------------------------------------
Agency API Access                | Required for cross-location reporting
Location Management              | Add/remove subaccounts from the system
API Rate Limiting                | 100ms delay between contact API calls
Max Retries                      | 3 retries with exponential backoff
Page Limit                       | 100 opportunities per API page

Reporting Settings:
-------------------
Setting                          | Default Value    | Description
---------------------------------|------------------|---------------------------
Group by Location                | Enabled          | Show location breakdown
Date Range                       | Previous Month   | Configurable month/year
Export Format                    | CSV              | Comma-separated values


================================================================================
                         SUB ACCOUNT SETTINGS
================================================================================

Sub Account (Location) Configuration:
-------------------------------------
Each subaccount requires:

1. Location ID
   - Unique identifier from GoHighLevel
   - Found in subaccount settings
   - Format: alphanumeric string

2. Location Name
   - Human-readable name for reports
   - Example: "Gym Downtown", "Fitness West"

3. Private Integration Token (API Key)
   - Generated in subaccount's Integrations settings
   - Required scopes: contacts.readonly, opportunities.readonly
   - Each location MUST have its own API key


Lead Source Mapping:
--------------------
Leads are grouped by the "Contact Source" field from each contact record.
Common source values include:

Source Type        | Example Values
-------------------|------------------------------------
Website Form       | "Website Form", "Landing Page"
Phone Call         | "Phone Call", "Inbound Call"
Chat Widget        | "Chat", "Live Chat"
Referral           | "Referral", "Word of Mouth"
Paid Advertising   | "Google Ads", "Facebook Ads"
Organic Search     | "Organic", "SEO"
Social Media       | "Facebook", "Instagram"
Email Campaign     | "Email", "Newsletter"


================================================================================
                         DATA FLOW DIAGRAM
================================================================================

    [GoHighLevel API]
         │
         ▼
    [Fetch Opportunities]  ◄── Location API Key
         │                     Date Range Filter
         ▼
    [Fetch Contacts]       ◄── Rate Limited (100ms delay)
         │                     Per Contact ID
         ▼
    [Extract Contact Source]
         │
         ▼
    [Aggregate by Source]  ◄── Group by Location (optional)
         │
         ├── Total Count
         ├── Total Value ($)
         ├── Open Count
         ├── Won Count
         ├── Lost Count
         └── Abandoned Count
              │
              ▼
         [Generate CSV]
              │
              ▼
         [Download Report]


================================================================================
                         OPPORTUNITY STATUSES
================================================================================

Status      | Description
------------|-------------------------------------------------------------
Open        | Active opportunity, not yet closed
Won         | Successfully converted lead
Lost        | Opportunity did not convert
Abandoned   | Opportunity was abandoned/dropped

Note: The status mapping uses case-insensitive matching and handles
variations like "closed-won", "won", "closedwon", etc.


================================================================================
                         TROUBLESHOOTING
================================================================================

Common Issues:

1. "Authentication failed (401/403)"
   - Verify API key is correct for the specific location
   - Check that required API scopes are enabled
   - Ensure API key hasn't expired

2. "No opportunities found"
   - Verify date range includes data
   - Check that opportunities exist in the location
   - Confirm location ID is correct

3. "Rate limiting errors"
   - The system automatically adds delays between requests
   - Reduce number of locations per report if issues persist

4. "Contact Source is empty"
   - Leads without a Contact Source appear as "(No Source)"
   - Update contact records in GoHighLevel to add source data


================================================================================
                         CONTACT & SUPPORT
================================================================================

For questions about lead source reporting configuration:
- EvolveCRM Support: support@evolvestrategists.com
- GoHighLevel Documentation: https://developers.gohighlevel.com

Generated: 2026-03-25 16:25:49
================================================================================