Create Segment Lists#

Build a library of segment lists that enable targeted marketing, accurate reporting, and proper suppression. These lists form the foundation of segment-based operations.

Prerequisites#

• HubSpot API token in .env
• Python with hubspot-api-client installed via uv
• ICP tier property created (run /create-icp-tiers first)
• Lifecycle stages cleaned up (run /fix-lifecycle-stages first)

Interview: Gather Requirements#

Before executing, collect the following information from the user:

Q1: What are your key customer segments?

• Examples: Industry verticals (Manufacturing, Professional Services, Retail, Education, Logistics), company size tiers (Enterprise, Mid-Market, SMB), geographic regions (North America, EMEA, APAC)
• Default: Core business segments (Customers, Partners, Competitors, Internal) plus ICP tiers and engagement-based segments

Q2: What engagement criteria define "active" for your business?

• Examples: Email open or click in last 90 days, website visit in last 60 days, form submission in last 30 days, meeting booked in last 90 days
• Default: Any email engagement (open or click) within the last 90 days

Recommended Segments#

Core Business Segments#

List NameTypeCriteriaAll CustomersActiveLifecycle stage = CustomerAll PartnersActiveContact type = Partner (or custom property)CompetitorsStaticManually curated from known competitor domainsInternal EmployeesActiveEmail domain matches company domainSuppressed ContactsActiveMarketing status = non-marketing OR globally unsubscribed

ICP-Based Segments#

List NameTypeCriteriaICP Tier 1ActiveICP tier property = Tier 1ICP Tier 2ActiveICP tier property = Tier 2ICP Tier 3ActiveICP tier property = Tier 3Non-ICPActiveICP tier property = Non-ICP or unknown

Industry Segments#

List NameTypeCriteria[Industry Name]ActiveIndustry = [value](Create one per target industry)

Engagement Segments#

List NameTypeCriteriaHighly Engaged (90 days)ActiveEmail open or click in last 90 daysDisengaged (6+ months)ActiveNo email engagement in 180+ daysNever EngagedActiveNo email opens ever AND created 30+ days ago

Step-by-Step Instructions#

Stage 1: Before — Plan Your Segments#

1. Review the segments above and decide which are relevant to your business.
2. Confirm the properties these lists depend on are populated (ICP tier, lifecycle stage, industry).
3. Check for existing lists that overlap — merge or rename rather than creating duplicates.

Stage 2: Execute — Create Lists#

Use the Lists API to create active (smart) lists:

python

from hubspot import HubSpot

api_client = HubSpot(access_token=os.getenv("HUBSPOT_API_TOKEN"))

# Example: Create "All Customers" list
api_client.crm.lists.lists_api.create(
    list_create_request={
        "name": "All Customers",
        "objectTypeId": "0-1",  # contacts
        "processingType": "DYNAMIC",
        "filterBranch": {
            "filterBranchType": "OR",
            "filters": [{
                "filterType": "PROPERTY",
                "property": "lifecyclestage",
                "operation": {
                    "operationType": "ENUMERATION",
                    "operator": "IS_EQUAL_TO",
                    "value": "customer"
                }
            }]
        }
    }
)

Create each list, verify member count, and document the list ID.

For static lists (Competitors), create the list and manually add contacts or import from a CSV.

Stage 3: After — Verify#

1. Check member counts for each list — do they match expectations?
2. Verify no contacts appear in mutually exclusive lists (e.g., both Customer and Competitor).
3. Confirm lists are visible to the appropriate teams.

Stage 4: Rollback#

• Lists can be deleted via the API or UI.
• Deleting a list does not affect the contacts in it — only the list definition is removed.
• Check if any workflows or emails reference the list before deleting.

Tips#

• Use a consistent naming convention: [Category] - Segment Name (e.g., [ICP] - Tier 1, [Industry] - Manufacturing).
• Review segment membership quarterly — segments should grow or shrink in expected ways.
• Use these lists as building blocks for email sends, ad audiences, and workflow enrollment triggers.