A lead represents a contact or prospect in the Lofty CRM. Nearly every other resource — tasks, transactions, activities, communications — is associated with a lead.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.
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 |
All lead IDs are 64-bit integers. JavaScript clients must handle these carefully — see JS / TS Integration.
Lifecycle
Leads move through four stages:- Capture — A lead is created via API, form submission, or third-party import. Lofty creates a lead record with contact info and source.
-
Routing — If no
assignedUserIdis provided, Lofty applies the team’s routing rules to automatically assign the lead to an agent. - 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.
- Conversion — The lead progresses through pipeline stages toward a closed deal. Transactions are created and associated with the lead.
Pipeline stages
Each lead has astage 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 (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.
Related resources
Lead Management Guide
Step-by-step: create, update, assign, and delete leads.
Leads API Reference
Full endpoint documentation with parameters and responses.