tomgranot/hubspot-admin-skills/create-icp-tiers

Create ICP Tier Property and Classification Workflows

Classify every company in the CRM into an Ideal Customer Profile tier based on firmographic data. Creates a custom dropdown property and 4 automated workflows that continuously classify companies as they enter or change.

Why This Matters

Without ICP classification, every inbound lead looks the same regardless of whether they come from a large enterprise in a target vertical or a tiny company in an irrelevant industry. Sales and marketing have no systematic way to prioritize outreach, allocate resources, or differentiate campaigns by company fit. ICP Tier is also a major input to the lead scoring model.

Prerequisites

• Super Admin permissions in HubSpot
• A HubSpot service key (HUBSPOT_ACCESS_TOKEN in .env; an existing legacy private app token also works) with company read/write and crm.schemas.companies.write scopes
• Python 3.10+ with `uv`
• Access to Automation > Workflows (Marketing Hub Professional or higher)
• Data enrichment processes completed (company name, industry, geo values) so company data is as complete as possible
• Company properties Number of Employees and Industry should be well-populated. Check coverage:
• Industry: aim for 80%+ populated
• Employee count: aim for 80%+ populated
• Companies missing these fields will fall to "Not ICP" (conservative, intentional)

Interview: Gather Requirements

Before executing, collect the following information from the user:

Q1: What industries define your ideal customer?

• Examples: Manufacturing, Professional Services, Logistics, Retail, Education, Media & Entertainment, Hospitality, Real Estate, Agriculture
• Default: No default -- this is highly business-specific and must be provided by the user

Q2: What employee count ranges define your tiers?

• Examples: Tier 1: 1,000+, Tier 2: 200-999, Tier 3: 50-199, Not ICP: under 50
• Default: Tier 1: 1,000+, Tier 2: 200-999, Tier 3: 50-199

Q3: Are there any other firmographic criteria?

• Examples: Annual revenue thresholds, geographic restrictions (US-only, EMEA, etc.), specific technologies used, funding stage
• Default: None -- industry and employee count are the primary classification axes

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/create-icp-tiers/ in a clone of the repo).

before.py checks whether the tier property exists and audits industry/employee-count coverage. execute.py creates the ICP Tier property (review its configuration block first). after.py verifies coverage and tier distribution. The classification workflows themselves are built in the UI (see Execute).

Plan

1. Define your ICP tier criteria (industry verticals + employee count thresholds)
2. Create the ICP Tier custom property via API or UI
3. Build 4 classification workflows (Tier 1, Tier 2, Tier 3, Not ICP)
4. Activate workflows in staggered sequence
5. Verify classification results (after state)

Before

Define Your ICP Tiers

Before building anything, define your criteria framework:

Size-based demotion pattern: Companies in a higher-tier industry but below that tier's employee threshold should be demoted to the next tier down, not classified as "Not ICP". For example:

• A company in a Tier 1 industry with fewer than 1,000 but more than 200 employees -> Tier 2
• A company in a Tier 2 industry with fewer than 200 but more than 50 employees -> Tier 3
• Only companies below 50 employees in any ICP industry, or in non-ICP industries entirely, should be "Not ICP"

This ensures ICP-relevant companies are never lost due to size alone.

Audit Current State

Run uv run scripts/before.py. The core queries:

# Check if the ICP Tier property already exists
# Use your chosen property name (e.g., "company_segment", "buyer_tier", "icp_tier")
PROPERTY_NAME = "company_segment"
resp = requests.get(f"{BASE}/crm/v3/properties/companies/{PROPERTY_NAME}",
                    headers=HEADERS)
print("Property exists" if resp.status_code == 200 else "Property does not exist yet")
# Check data coverage for classification
for prop_name in ["industry", "numberofemployees"]:
    resp = requests.post(f"{BASE}/crm/v3/objects/companies/search", headers=HEADERS, json={
        "filterGroups": [{"filters": [
            {"propertyName": prop_name, "operator": "NOT_HAS_PROPERTY"},
        ]}],
        "limit": 1,
    })
    print(f"Companies missing {prop_name}: {resp.json()['total']}")

Execute

Step 1: Create the ICP Tier Property

Choose a property name that fits your CRM conventions (e.g., company_segment, buyer_tier, or icp_tier). The name is configurable -- just be consistent across workflows and lists.

Via API (recommended): run uv run scripts/execute.py, which posts:

# Configure your property name here
PROPERTY_NAME = "company_segment"
resp = requests.post(f"{BASE}/crm/v3/properties/companies", headers=HEADERS, json={
    "name": PROPERTY_NAME,
    "label": "ICP Tier",
    "type": "enumeration",
    "fieldType": "select",
    "groupName": "companyinformation",
    "description": "Automated ICP classification based on industry and employee count. "
                   "Set by workflow - do not edit manually.",
    "options": [
        {"label": "Tier 1 - Primary ICP", "value": "tier_1_primary_icp", "displayOrder": 0},
        {"label": "Tier 2 - Secondary ICP", "value": "tier_2_secondary_icp", "displayOrder": 1},
        {"label": "Tier 3 - Tertiary ICP", "value": "tier_3_tertiary_icp", "displayOrder": 2},
        {"label": "Not ICP", "value": "not_icp", "displayOrder": 3},
    ],
})
resp.raise_for_status()

Via UI: Settings > Properties > Company properties > Create property > Dropdown select with the four tier options.

Step 2: Build Classification Workflows

Build 4 company-based workflows in the HubSpot UI. Workflows must use filter-based triggers ("When filter criteria is met") with AND logic.

Building the Classification Workflows: Three Options

Option 1: Manual UI Build. Follow the per-workflow specifications below. This is the most reliable method and gives you full control over every trigger and action.

Option 2: HubSpot Breeze AI. Navigate to Automation > Workflows > Create workflow > "Describe what you want" and paste the following prompt (repeat for each tier, adjusting the tier name, industries, and thresholds):

Create a company-based workflow that triggers when filter criteria is met:
- Number of Employees is greater than or equal to [THRESHOLD]
- AND Industry is any of [LIST YOUR INDUSTRIES]
- AND the custom property "ICP Tier" is unknown
 
The workflow should set the custom property "ICP Tier" to "[TIER VALUE]".
Enable re-enrollment for all trigger properties.

For the Not ICP catch-all workflow, use:

Create a company-based workflow that triggers when filter criteria is met:
- Custom property "ICP Tier" is unknown
 
The workflow should wait a delay (30-90 minutes) to let tiered workflows process first, then set the custom property "ICP Tier" to "Not ICP".
Enable re-enrollment.

CRITICAL WARNING: Breeze trigger limitations. Breeze creates event-based triggers (OR logic) instead of filter-based triggers (AND logic). This is especially dangerous for ICP classification because event-based triggers fire when any single property changes, regardless of other conditions, leading to incorrect tier assignments. After Breeze creates each workflow, you MUST manually verify and rebuild the triggers to use filter-based enrollment with AND logic. Breeze is best used for creating the workflow skeleton (actions, delays) -- the trigger conditions almost always need manual correction.

Additional Breeze limitations:

• Breeze cannot create "is unknown" filter conditions reliably -- verify that the "ICP Tier is unknown" guard is correctly configured
• Breeze cannot configure re-enrollment rules
• Breeze cannot create multiple filter groups with OR between groups and AND within groups (needed for Tier 2 and Tier 3 demotion logic)

Option 3: Claude Anthropic Chrome Extension. The Claude Chrome extension lets Claude see and interact with the HubSpot workflow builder UI directly. You can describe each workflow's logic in natural language and Claude will click through the UI to build it. This is often more accurate than Breeze for the ICP workflows because of their complex multi-group filter logic and the critical requirement for AND-based triggers. Build the four workflows one at a time, activating in the staggered sequence described in Step 3.

Workflow Specifications

Workflow 1: Tier 1 (Primary ICP)

• Name: ICP TIER: Assign Tier 1 - Primary ICP
• Trigger: When filter criteria is met
• Number of Employees >= [your threshold, e.g., 1,000]
• AND Industry is any of [your primary verticals and their variants]
• Re-enrollment: ON (for all trigger properties)
• Action: Set ICP Tier = "Tier 1 - Primary ICP"

Industry variant tip: HubSpot has multiple labels for the same vertical. For example, "Manufacturing" might appear as "Manufacturing", "Industrial Automation", "Machinery", "Electrical/Electronic Manufacturing". Include ALL relevant variants in the "is any of" filter. Check what values actually exist in your data.

Workflow 2: Tier 2 (Secondary ICP)

• Name: ICP TIER: Assign Tier 2 - Secondary ICP
• Trigger: When filter criteria is met

Filter Group 1 — Secondary industries at threshold:

• Number of Employees >= [e.g., 200]
• AND Industry is any of [your secondary verticals and variants]
• AND ICP Tier is unknown (prevents overwriting Tier 1)

Filter Group 2 — Primary industries demoted by size:

• Number of Employees >= [e.g., 200]
• AND Number of Employees <= [e.g., 999]
• AND Industry is any of [your primary verticals and variants]
• AND ICP Tier is unknown

• Re-enrollment: ON
• Action: Set ICP Tier = "Tier 2 - Secondary ICP"

Workflow 3: Tier 3 (Tertiary ICP)

• Name: ICP TIER: Assign Tier 3 - Tertiary ICP
• Trigger: When filter criteria is met
• Multiple filter groups for:
• Tertiary industries at threshold
• Primary industries demoted by size (below Tier 2 threshold)
• Secondary industries demoted by size (below Tier 2 threshold)
• Each group includes AND ICP Tier is unknown
• Re-enrollment: ON
• Action: Set ICP Tier = "Tier 3 - Tertiary ICP"

Workflow 4: Not ICP (Catch-All)

• Name: ICP TIER: Assign Not ICP
• Trigger: When filter criteria is met
• ICP Tier is unknown
• Re-enrollment: ON
• Action 1: Delay (30-90 minutes) to let tiered workflows process first
• Action 2: Set ICP Tier = "Not ICP"

Step 3: Activation Sequence

Activate workflows in staggered sequence to prevent race conditions: