> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reach.raysium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Leads Overview

> Understanding leads and contact management in Reach

## What are Leads?

Leads are contacts in your Reach CRM - people you can communicate with through Telegram campaigns. Each lead represents a potential customer or contact with associated information, interaction history, and relationship data.

Leads are the foundation of your outreach strategy. They can be added manually, imported from files, extracted from Telegram groups, or automatically created when they interact with your campaigns.

## Core Lead Information

### Identifiers

Every lead requires at least one identifier to enable Telegram communication:

* **Telegram User ID**: Unique numeric identifier (most reliable, works even without username/phone)
* **Username**: Telegram @username (optional, can change)
* **Phone Number**: Contact's phone number (optional, may be private)

### Contact Details

* **First Name** / **Last Name**: Display names
* **Country**: Country code for localization
* **Language**: Preferred language for messaging
* **Profile Picture**: Automatically fetched from Telegram when available

### Metadata

* **Source**: Origin of the lead (manual, crawling, file\_upload, campaign, etc.)
* **Status**: `active`, `blocked`, or `archived`
* **Priority**: `high`, `medium`, or `low` for prioritization
* **Group Name**: Telegram group/channel where lead was found
* **Tags**: Custom labels for organization
* **Custom Fields**: Additional structured data you define

## Lead Sources

### Manual Entry

Add leads individually through the interface. Requires at least username or phone number. Supports deduplication - if a lead with the same identifier exists, it's updated instead of creating a duplicate.

### File Import (CSV/Excel)

Bulk import leads from CSV or Excel files. The system processes files in batches for performance (200-500 contacts/second). Automatic deduplication ensures no duplicates are created.

**Required columns**: `first_name`, `last_name`, `username`, `phone_number`

**Optional columns**: `country`, `language`, plus any custom field names

### Group Crawling

Extract leads from Telegram groups and channels using multiple crawling methods. The system intelligently selects the best method based on rate limits and availability. Results are cached for 24 hours to avoid redundant API calls.

See the [Crawling Guide](/leads/crawling) for detailed information on methods, rate limits, and best practices.

### Campaign Interactions

Leads are automatically created when:

* They receive campaign messages
* They respond to campaigns
* They interact with your Telegram accounts

## Lead Statuses

### Active

Default status for all new leads. Active leads:

* Can receive campaign messages
* Are included in segment matching
* Appear in campaign contact selection
* Count toward your lead statistics

### Blocked

Leads who have blocked your Telegram account. Blocked leads:

* Cannot receive messages (Telegram API restriction)
* Are automatically excluded from campaigns
* May indicate messaging strategy issues if rate is high
* Can be manually changed back to active if unblocked

### Archived

Leads that are no longer actively managed. Archived leads:

* Are excluded from campaigns and segments
* Preserve all historical data
* Can be restored to active status
* Useful for organizing inactive contacts

## Organization Context

### Personal Workspace

When not in an organization, leads belong to you exclusively. Only you can view and edit your leads.

### Organization Mode

When in an organization, leads can be shared across team members:

**View Permissions:**

* **Own Leads**: All members can view their own leads (default view)
* **All Leads**: Owners and Admins can view all organization leads
* **Members**: Can view all leads if organization settings allow

**Edit Permissions:**

* **Own Leads**: Full edit access for creator
* **Organization Leads**: Any organization member can edit any lead in the organization
* **Deletion**: Only creator or Owner/Admin can delete leads

**Data Isolation:**

* Leads are scoped to the organization
* Switching organizations shows different lead sets
* Personal workspace leads are separate from organization leads

## Deduplication

The system automatically prevents duplicate leads using intelligent matching:

1. **Primary Match**: Same `telegram_user_id` (most reliable)
2. **Secondary Match**: Same `username` (case-insensitive)
3. **Tertiary Match**: Same `phone_number` (normalized)

When a duplicate is detected:

* Existing lead is updated with new information
* Historical data (campaigns, messages, deals) is preserved
* No duplicate records are created

This applies to all lead creation methods: manual entry, file upload, crawling, and campaign interactions.

## Next Steps

<Card title="Managing Leads" icon="users" href="/leads/managing-leads">
  Learn how to add, search, filter, and organize leads
</Card>

<Card title="Group Crawling" icon="database" href="/leads/crawling">
  Extract leads from Telegram groups with intelligent rate limiting
</Card>

<Card title="CRM View" icon="briefcase" href="/leads/crm-view">
  Understand the lead detail page, activities, intelligence, and messaging
</Card>