Leads

Potential customers and incoming inquiries tracked via HubSpot Integration. Leads represent the earliest stage of the sales funnel before conversion to Contacts and Companies.

HubSpot mirror: hubspot_leads mirrors the HubSpot Lead object (objectTypeId 0-136, leadConfig in services/hubspot/sync-engine/entity-configs.ts). hubspotId is for sync round-tripping only — internal references join on the UUID PK.

Source Files

Layer	Path
Schema	backend/src/db/schema.ts (hubspotLeads)
Backend	backend/src/routes/admin/hubspot-sync.ts (leads endpoints at /leads, /leads/:id)
Pages	frontend/src/pages/LeadsPage.tsx, frontend/src/pages/LeadDetailPage.tsx

Database Table

Table	Purpose
hubspot_leads	HubSpot-synced leads with pipeline, status, and association references

Key Fields

Field	Type	Notes
hubspotId	varchar(100)	HubSpot Lead object ID (unique, required)
hubspotContactId	varchar	Associated HubSpot contact ID
contactId	uuid FK	Local contact reference (nullable)
hubspotCompanyId	varchar	Associated HubSpot company ID
companyId	uuid FK	Local company reference (nullable)
leadName	varchar(255)	Display name of the lead
leadStatus	varchar(100)	Current status in the pipeline
leadLabel	varchar(100)	Classification label
hubspotPipeline	varchar	HubSpot pipeline identifier
hubspotPipelineStage	varchar	Current stage within the pipeline
recordOwnerContactId	uuid FK	Read-only sync mirror of the HubSpot record owner, resolved to a contact via hubspot_owners (replaced the old hubspotOwnerId varchar — PR#1767); sync layer is the sole writer
hubspotProperties	jsonb	Full HubSpot property bag
hubspotSchemaVersion	varchar(20)	Schema version for sync compatibility
lastSyncedAt	timestamp	Last sync timestamp
archived, archivedAt, deletedAt	bool/timestamp	Soft archive + privacy deletion
archiveReason	text	Why the lead was archived
mergedIntoHubspotId	varchar	If lead was merged into another

Relationships

Lead *──0..1 Contact (local contact reference)
Lead *──0..1 Company (local company reference)

Leads may reference both a HubSpot contact/company ID and a local contact/company record once the association is established.

API Endpoints

Leads are served through the HubSpot admin sync routes:

Method	Path	Purpose
GET	/api/admin/hubspot/sync/leads	Paginated lead list
GET	/api/admin/hubspot/sync/leads/:id	Single lead detail

Leads are synced as part of the full HubSpot sync process (with syncLeads flag).

Conversion Flow

HubSpot Lead -> Sync -> hubspot_leads table
                     -> Associate with local Contact/Company
                     -> Convert to Building/Project (manual)

When a lead converts, the associated contact and company records serve as the basis for creating Buildings and Projects.

Features

• HubSpot-native — leads originate and are primarily managed in HubSpot CRM
• Pipeline tracking with stage progression synced from HubSpot
• Soft archive with reason tracking and merge detection
• Association linking to local Contacts and Companies records

Related Pages

Contacts | Companies | Buildings | Projects | HubSpot Integration | Admin Dashboard