Fix Lifecycle Stages

Ensure every contact and company has an appropriate lifecycle stage. This includes backfilling missing stages, correcting disallowed stage values, and creating prevention workflows that automatically assign stages to new records.

Why This Matters

Records without a lifecycle stage are invisible in pipeline reports, excluded from stage-based workflows, and cannot be properly segmented. Even a small percentage of missing lifecycle stages corrupts funnel reporting and makes pipeline analytics unreliable. Lifecycle stage data is also a prerequisite for lead scoring models and lifecycle progression workflows.

Prerequisites

• Phase 1 hygiene processes completed (invalid/deleted contacts removed first)
• A HubSpot private app access token (HUBSPOT_ACCESS_TOKEN in .env) with contact and company read/write scopes
• Python 3.10+ with uv
• Access to Contacts and Companies with bulk edit permissions
• Access to Automation > Workflows
• Understanding of HubSpot's lifecycle stage progression rules (see Critical Concept below)

Scripts