Skip to main content
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

All lead IDs are 64-bit integers. JavaScript clients must handle these carefully — see JS / TS Integration.

​
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 (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.
Use the V2 activities endpoint for new integrations — it provides a complete picture in a single response.

Lead Management Guide

Step-by-step: create, update, assign, and delete leads.

Leads API Reference

Full endpoint documentation with parameters and responses.