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

# Leads

> Understand the lead data model, lifecycle, and routing in Lofty.

A lead represents a contact or prospect in the Lofty CRM. Nearly every other resource — tasks, transactions, activities, communications — is associated with a lead.

## Data model

| Field                    | Type      | Description                                                                                                   |
| ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------- |
| `leadId`                 | int64     | Unique identifier                                                                                             |
| `firstName` / `lastName` | string    | Name (max 30 chars each)                                                                                      |
| `emails`                 | string\[] | Email addresses                                                                                               |
| `phones`                 | string\[] | Phone numbers                                                                                                 |
| `assignedUserId`         | int64     | Assigned agent's user ID                                                                                      |
| `stage`                  | string    | Pipeline stage name                                                                                           |
| `source`                 | string    | Lead source label                                                                                             |
| `score`                  | int32     | Lead score                                                                                                    |
| `tags`                   | object\[] | Applied tags                                                                                                  |
| `leadTypes`              | int32\[]  | Type IDs: Buyer (2), Seller (1), Renter (5), Investor (6), Agent (7), Homeowner (8), Landlord (9), Other (-1) |
| `teamId`                 | int64     | Team the lead belongs to                                                                                      |

<Note>
  All lead IDs are 64-bit integers. JavaScript clients must handle these carefully — see [JS / TS Integration](/javascript-integration).
</Note>

## Lifecycle

Leads move through four stages:

1. **Capture** — A lead is created via API, form submission, or third-party import. Lofty creates a lead record with contact info and source.

2. **Routing** — If no `assignedUserId` is provided, Lofty applies the team's routing rules to automatically assign the lead to an agent.

3. **Working** — The assigned agent works the lead. Activities (calls, emails, texts) are tracked in the lead's timeline. Agents can add leads to the working pool for AI assistant follow-up.

4. **Conversion** — The lead progresses through pipeline stages toward a closed deal. Transactions are created and associated with the lead.

## Pipeline stages

Each lead has a `stage` that reflects where it is in the sales process. Stages are configurable per team. Common stages include New Lead, Contacted, Qualified, Under Contract, and Closed.

Stage changes trigger [Pipeline Change webhooks](/concepts/webhooks#12-pipeline-change) (listId: 12).

## Hidden leads

When a lead has visibility restrictions, only the assigned agent receives webhook notifications and can access the lead. Other team members — including admins — are excluded.

## Activities

The activity timeline captures all interactions with a lead:

* **V1** (`GET /v1.0/leads/{leadId}/activities`) — Site activities: property views, favorites, searches.
* **V2** (`GET /v2.0/leads/{leadId}/activities`) — Unified timeline: calls, texts, emails, and agent-logged communications in chronological order.

<Tip>
  Use the V2 activities endpoint for new integrations — it provides a complete picture in a single response.
</Tip>

## Related resources

<CardGroup cols={2}>
  <Card title="Lead Management Guide" icon="list-check" href="/guides/lead-management">
    Step-by-step: create, update, assign, and delete leads.
  </Card>

  <Card title="Leads API Reference" icon="code" href="/api-reference/leads/overview">
    Full endpoint documentation with parameters and responses.
  </Card>
</CardGroup>