new-contact-hygiene-workflow

Files (4)

• SKILL.md
• after.py · scripts/
• before.py · scripts/
• execute.py · scripts/

SKILL.md (first lines)

# New Contact Hygiene Workflow

Build a workflow that automatically enriches every new contact at creation time. This ensures contacts enter the database with a lifecycle stage, company name, and industry before any human touches them.

## What Is and Isn't Scriptable

**API status:** HubSpot documents the Workflows API as **beta** and subject to change. Its current reference is the date-based beta path `/automation/v4/2027-03-beta/flows`; this skill's scripts still call the unversioned `/automation/v4/flows` path, which v4's end of support on March 30, 2027 also covers. Creating workflows disabled and reviewing them in the UI is what makes a beta API acceptable here. If a script's create call starts failing, the manual UI build below is the fallback.

The v4 Automation API creates workflows programmatically, including "is unknown" enrollment conditions via `LIST_BASED` filter criteria. Two pieces of this particular design still belong in the UI:

1. **Copy from associated object** actions (copy company name/industry from the associated company) have no documented v4 action fields. Add them in the UI during review — or build the action once in the UI, `GET /automation/v4/flows/{flowId}`, and extend the script with the exact field shapes your portal returns.
2. **The notification branch** (alert admin when a contact still has no company after the delay) depends on portal-specific recipients.

So the split is: the script creates the default-lifecycle-stage workflow via API; the enrichment copy actions and the notification branch are added in the UI. If you already run `/enrich-company-name` and `/enrich-industry`, their dedicated workflows cover the copy actions and this skill's API-created workflow completes the intake picture.

## Prerequisites

- HubSpot Marketing Professional or Enterprise plan
- A HubSpot service key (`HUBSPOT_ACCESS_TOKEN` in `.env`; an existing legacy private app token also works) with the `automation` scope (for the API path)
- Python 3.10+ with [`uv`](https://github.com/astral-sh/uv)
- Workflow creation permissions in HubSpot
- Company association enrichment completed (run `/enrich-company-name` and `/enrich-industry` first for existing contacts)

## Scripts

Script paths are relative to this skill's directory. Run them from your project directory so `.env`, `data/`, and `reports/` resolve there: prefix each path with wherever this skill is installed (`skills/new-contact-hygiene-workflow/` in a clone of the repo).

| Stage | Script | Run with |
|-------|--------|----------|
| Before | [`scripts/before.py`](./scripts/before.py) | `uv run scripts/before.py` |
| Execute | [`scripts/execute.py`](./scripts/execute.py) | `uv run scripts/execute.py` |
| After | [`scripts/after.py`](./scripts/after.py) | `uv run scripts/after.py` |

`execute.py` creates one workflow — "HYGIENE: Default Lifecycle Stage for New Contacts" (enrollment: create date known AND lifecycle stage unknown; action: set stage to Lead; re-enrollment on) — **disabled, for review before enabling**. Extend it in the UI with the copy actions and notification branch per the design below.

## Building the Workflow: Two Options

**Option A (primary):** run the scripts, then extend the created workflow in the UI with the copy-from-associated-company actions, the delay, and the no-company notification branch (Stage 3, steps 3-6).

**Option B:** build the whole workflow manually in the UI (all of Stage 3).

**Alternatives:** HubSpot Breeze AI provides minimal value for this workflow — it creates event-based (OR) triggers, and cannot create "is unknown" conditions, copy-from-association actions, or re-enrollment rules. The Claude Chrome extension can drive the workflow builder UI directly and handles those cases. Both are secondary options.

## Workflow Design

```
TRIGGER: Contact create date is known
         (fires for every new contact)
           │
           ▼
    ┌─────────────────────────┐
    │ Set lifecycle stage      │
    │ = "Lead" (if empty)      │
    └────────────┬────────────┘
                 │
                 ▼
    ┌─────────────────────────┐
    │ Copy company name from   │
    │ associated company       │
    └────────────┬────────────┘
                 │
                 ▼
    ┌─────────────────────────┐
    │ Copy industry from       │
    │ associated company       │
    └────────────┬────────────┘
                 │
                 ▼
    ┌─────────────────────────┐
    │ Delay: short wait         │
    │ (3-10 min, rec: 5)      │
    └────────────┬────────────┘
                 │
                 ▼
    ┌─────────────────────────┐
    │ IF/THEN BRANCH:          │
    │ Company name is unknown? │
    ├──────────┬──────────────┘
    │ YES      │ NO
    │          │
    ▼          ▼
  Retry      Continue
  copy       (enriched)
  + notify
  admin
```

## Step-by-Step Build Instructions

### Stage 1: Plan

1. Confirm the default stage for new contacts (Lead, unless your funnel differs).
2. Decide who receives the "no company association" notification.

### Stage 2: Before

1. Confirm company enrichment processes have run for existing data.
2. Run `uv run scripts/before.py` to inventory workflows and check name collisions.

### Stage 3: Execute

**Option A:** run `uv run scripts/execute.py`, then open the created workflow in the UI and continue from step 3 below (copy actions, delay, branch). **Option B:** open HubSpot > Automation > Workflows > Create workflow, select "Contact-based", start from scratch, and follow all steps.

1. **Set enrollment trigger:**
   - Property: "Create date" > "is known"
   - This enrolls every new contact automatically.

2. **Add action: Set property value**
   - Property: "Lifecycle stage"
   - Value: "Lead"
   - Condition: Only if lifecycle stage is unknown (use an if/then branch before this step, or rely on HubSpot's "only if empty" option if available in your plan).

3. **Add action: Copy property**
   - Source: Associated company > "Company name"
   - Target: Contact > "Company" property

4. **Add action: Copy property**
   - Source: Associated company > "Industry"
   - Target: Contact > "Industry" property

From TomGranot/hubspot-admin-skills, MIT.

More from TomGranot/hubspot-admin-skills