Cleanup Lead Owners

Remove departed employees from HubSpot and reassign their CRM records. Orphaned records with no active owner fall through the cracks.

Prerequisites

• A HubSpot private app access token (HUBSPOT_ACCESS_TOKEN in .env) with crm.objects.owners.read and contact/company/deal write scopes
• Python 3.10+ with uv
• A list of current employees (to compare against HubSpot users)
• A default owner or round-robin assignment rule for orphaned records

Step-by-Step Instructions

Stage 1: Plan

Confirm with the user before starting:

1. Who receives reassigned records — a single default owner, or territory/round-robin rules?
2. Which flagged users should be deactivated vs merely stripped of records?