During a working session on 2026-03-26, Mark and Karly used an AI agent (Claude via a local agentic workspace) to clean up Citrus America's HubSpot CRM instance. The work involved consolidating duplicate and redundant contact properties, updating dependent forms and workflows, and reassigning ~3,000 contacts from an archived user. Tasks that would have taken a day or more manually were completed in a single session.
This article documents what was done, the challenges encountered, and the reusable patterns that emerged.
Related: [1] · [2]
Problem: Two country fields existed — one text input and one dropdown — with inconsistent values (capitalization errors, free-text entries).
Resolution:
- Converted the text field to a dropdown with 17 standardized options (including "Other")
- Normalized existing values (e.g., "united states" → "United States")
- Backfilled ~2,700 contacts using HubSpot's stored IP country data, mapped to clean dropdown values
- Archived the legacy text field
Notes: IP-based backfill is reliable at the country level; VPN usage rarely distorts country-level data for this use case.
Problem: Three user-facing state fields existed: a messy text field (state, ~7,000 contacts), a dropdown (state_or_region), and an IP-derived field. The client only needed U.S. states.
Resolution:
- Consolidated into the standard HubSpot state dropdown field using full state names (not abbreviations)
- Normalized ~8,730 contacts in a batched update
- Archived the redundant state_or_region field
Challenge — Forms and Workflows: The legacy field was referenced in 9 forms and 2 workflows. The AI agent initially flagged this as a manual step, but when pushed, it successfully automated the updates using the HubSpot v3 API (the v4 API was not backward compatible for this operation).
Remaining Manual Step: One form embedded in Jacob's meeting link could not be updated via API due to HubSpot's new form editor API tier restrictions. This must be updated manually in the HubSpot UI.
Action: Karly to manually update Jacob's meeting-link form to use the correct
statedropdown field.
Problem: Three overlapping fields existed:
1. Are you already juicing? — dropdown with granular options (Yes/No variants with detail)
2. Are you currently juicing? — Boolean checkbox
3. Are you juicing in your food service operation? — separate field
Resolution:
- Designated Are you already juicing? (dropdown) as the canonical field — preferred because it captures more granular data than a Boolean
- Migrated data from the Boolean and food-service fields into the dropdown, mapping yes/no values to the appropriate dropdown options
- Updated dependent forms automatically (agent applied the pattern learned from the State field cleanup without being prompted)
- Archived the redundant fields
Remaining Manual Step: Same API tier limitation as the State field — one form in Jacob's meeting link requires a manual update.
Problem: Two overlapping fields: Lead Source (standard HubSpot field) and Inbound Lead Source (custom). Also present: How did you hear about us? and How did you hear about us? (detail).
Resolution:
- Merged data from Inbound Lead Source into the standard Lead Source field
- Updated Lead Source and Lead Source Detail for all contacts via a bulk import using a cleanup CSV
Notes: Keeping the standard HubSpot Lead Source field (rather than a custom one) ensures compatibility with native HubSpot reporting.
Problem: ~3,000 contacts were assigned to Jay Gardner, an archived/inactive user.
Resolution:
- Bulk-reassigned all contacts from Jay Gardner to Jacob using the API
- Completed in a single automated operation
HubSpot's v4 form editor API is not backward compatible with v3. When the agent encountered v4-gated forms, it fell back to v3 patch methods. In one case (Jacob's meeting link), this was not possible and required a manual UI update.
The AI agent will sometimes claim a task requires manual intervention when it can actually be automated. The correct response is to push back explicitly. In this session, pushing the agent on the 9-form/2-workflow update resulted in full automation. This is a consistent behavior pattern worth knowing.
See [2] for the general framework.
Archiving or replacing a field that is used in forms, workflows, or object associations can silently break automations. Always let the agent audit field dependencies before making changes. HubSpot will block deletion of in-use fields but will allow hiding — which can cause workflows to malfunction if they depend on the hidden field.
When providing cleanup tasks to the AI agent, JSON or CSV format is significantly more efficient than prose notes. The agent parses structured data faster, with less ambiguity. Karly's action item is to compile remaining cleanup tasks into a single structured document before the next session.
The following tasks were identified but not completed in this session: