HubSpot Company State/Region Validator

This tool scans all HubSpot company records and validates their State/Region properties against a predefined list of US states, Canadian provinces, and Mexican states. It provides automated corrections for common spelling errors and abbreviations, and offers an interactive interface to manually correct or skip records that cannot be resolved automatically. Companies identified as being in countries outside the target regions (US, Canada, and Mexico) are automatically skipped.

Features

• Paging Support: Fetches and processes all companies in batches of 100 via HubSpot CRM v3 API.
• Foreign Country Filtering: Automatically ignores companies located outside of the target regions (US, Canada, and Mexico) if their country field is populated. This prevents false positive suggestion prompts for foreign state/region names (e.g., "Madrid" in Spain or "Bavaria" in Germany).
• Fuzzy Matching: Automatically suggests spelling corrections for state/region names (e.g., misspelled names or variations).
• Auto-expansion: Expands 2-letter abbreviations to their full names (e.g., CA -> California).
• Country Disambiguation: Uses the company's country (US, Canada, Mexico) to resolve overlapping 2-letter codes (e.g., BC for British Columbia, Canada vs. Baja California, Mexico).
• Auto-population: Automatically populates the 2-letter State/Region Code field if only the full name is present, or vice-versa when safe.
• Interactive Correction Loop: Allows users to approve suggestions, enter manual entries, skip records, or quit.
• Checkpointing: Automatically saves progress to company_states_checkpoint.json so you can stop and resume the script at any time without losing progress.
• Detailed Logging: Records actions to stdout and to verify_company_states.log.

---

Prerequisites

• Python 3.6+
• HubSpot Private App Token: Requires read/write access to CRM Company objects.
• HubSpot Portal ID: Your HubSpot Account/Portal ID (e.g., 12345678).

---

Setup Instructions

1. Clone or Navigate to the Repository Directory:

   cd /path/to/state-validator

2. Create and Activate a Virtual Environment (Recommended): On macOS/Linux:

   python3 -m venv .venv
   source .venv/bin/activate

   On Windows:

   python -m venv .venv
   .venv\Scripts\activate

3. Install Dependencies:

   pip install -r requirements.txt

---

How to Run

Execute the script by providing your HubSpot Portal ID as a positional argument.

python verify_company_states.py <portal_id> [--state-code-prop <property_name>]

Arguments & Options

• portal_id: (Required) Your HubSpot account's Portal ID (e.g., 12345678).
• --state-code-prop: (Optional) The internal API name of the State/Region Code property in HubSpot. Defaults to state_code. The script also automatically scans and checks for hs_state_code and state_region_code.

Example Run

python verify_company_states.py 12345678

1. Token Input: You will be prompted to enter your HubSpot Private App Token securely:

   HubSpot Private App Token : 
   

   (Note: The characters will not display as you type for security.)

2. Property Detection: The script will verify if the specified State/Region Code property exists. If the property is not found, you will be warned and asked if you want to proceed.

3. Pre-scan: The script fetches all companies, bypasses empty records, and automatically corrects standard abbreviation or missing code cases.

4. Interactive Validation Loop: For remaining invalid state/region values, the script prints details and prompts you for action:

   Company [1/15]: Acme Corp (acme.com) | ID: 123456789
     Current Country     : US
     Current State/Region: 'Californa'
     Current Code        : 'CA'
   ------------------------------------------------------------
     [Suggestion] Full Name: California
     [Suggestion] Code     : CA
   Choose action ([A]ccept Suggestion | [M]anual Entry | [S]kip | [Q]uit) [A]: 
   

   • [A]ccept Suggestion: Applies the suggested full name and/or code to the company in HubSpot.
   • [M]anual Entry: Prompts you to type a state name (must match allowed states or be explicitly overridden) and code.
   • [S]kip: Skips the company for this run.
   • [Q]uit: Safely saves progress to the checkpoint file and terminates execution.

Resuming Progress

If you quit the script midway (using q or Ctrl+C), a checkpoint file company_states_checkpoint.json will be saved. The next time you run the script, it will automatically detect the checkpoint and resume from where you left off. The checkpoint file is automatically deleted once all invalid records are successfully processed.

---

Log Output

All changes and exceptions are logged with timestamps in verify_company_states.log. You can tail or inspect this file to verify what updates were applied to your HubSpot portal:

tail -f verify_company_states.log