Standardize Country and State/Region Values

Convert inconsistent geographic formats (e.g., "US", "USA", "U.S." vs "United States"; "NY" vs "New York") to a single standard format across all contact and company records.

Why This Matters

Inconsistent geo values break geographic segmentation. A list filtering for "United States" will miss contacts labeled "US" or "USA". For B2B companies running region-specific campaigns or reporting by geography, this means inaccurate audience sizes and missed contacts.

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 views with bulk edit permissions
• Key constraint: If your CRM integrates with another system (e.g., Salesforce, marketing automation), agree on the standard format (full names vs. ISO codes) with that system's admin BEFORE standardizing. Mismatched formats between synced systems will cause ongoing data conflicts.
• Decision on standard format. This skill recommends:
  • Countries: Full names (e.g., "United States", "United Kingdom")
  • States (contact level): Full names (e.g., "New York", "California")
  • This matches HubSpot's default form behavior