Fix Lifecycle Stages

intent

Ensure every contact and company in HubSpot has an appropriate lifecycle stage assigned. Records without a lifecycle stage are invisible in pipeline reports, excluded from stage-based workflows, and cannot be properly segmented. This skill backfills missing stages based on context (associated company or deal status), corrects records stuck at disallowed stages, and installs prevention workflows to stop the problem from recurring. Run this skill once to audit and fix, then rely on the workflows to keep data clean going forward.

inputs

HubSpot API access:

• Environment variable: HUBSPOT_API_TOKEN (private app token or OAuth token with scopes: crm.objects.contacts.read, crm.objects.contacts.write, crm.objects.companies.read, crm.objects.companies.write, crm.objects.deals.read)
• API rate limit: 10 requests per second for standard tier; batch endpoints allow up to 100 records per call

HubSpot account requirements:

• Contacts and Companies objects with bulk edit permissions enabled
• Access to Automation > Workflows for creation of prevention workflows
• Deals object (if using deal context to determine company lifecycle stage)

Pre-requisites:

• Phase 1 hygiene complete (invalid or deleted contacts already removed from database)
• Understanding of HubSpot's forward-only lifecycle stage progression rule (see procedure step 2)
• Definition of which lifecycle stage values are "disallowed" in your business (e.g., "Subscriber", "Other", "Evangelist") and their correct mappings

External context needed:

• List of current lifecycle stages in use and their definitions
• Deal status mapping (e.g., "Closed Won" indicates Customer stage, "Open" indicates Opportunity stage)
• Associated company context for contacts (must be fetched via API association endpoint or lists in HubSpot)

procedure

Step 1: Audit current state

Run this script to count contacts and companies at each lifecycle stage and identify missing assignments:

import os
from hubspot import HubSpot
from dotenv import load_dotenv

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

# Count contacts with no lifecycle stage
result = api_client.crm.contacts.search_api.do_search(
    public_object_search_request={
        "filterGroups": [{
            "filters": [{
                "propertyName": "lifecyclestage",
                "operator": "NOT_HAS_PROPERTY"
            }]
        }],
        "limit": 0
    }
)
print(f"Contacts missing lifecycle stage: {result.total}")

# Count contacts at each stage
stages = ["subscriber", "lead", "marketingqualifiedlead", "salesqualifiedlead",
          "opportunity", "customer", "evangelist", "other"]
for stage in stages:
    result = api_client.crm.contacts.search_api.do_search(
        public_object_search_request={
            "filterGroups": [{
                "filters": [{
                    "propertyName": "lifecyclestage",
                    "operator": "EQ",
                    "value": stage
                }]
            }],
            "limit": 0
        }
    )
    if result.total > 0:
        print(f"  {stage}: {result.total}")

# Repeat for companies
result = api_client.crm.companies.search_api.do_search(
    public_object_search_request={
        "filterGroups": [{
            "filters": [{
                "propertyName": "lifecyclestage",
                "operator": "NOT_HAS_PROPERTY"
            }]
        }],
        "limit": 0
    }
)
print(f"\nCompanies missing lifecycle stage: {result.total}")

for stage in stages:
    result = api_client.crm.companies.search_api.do_search(
        public_object_search_request={
            "filterGroups": [{
                "filters": [{
                    "propertyName": "lifecyclestage",
                    "operator": "EQ",
                    "value": stage
                }]
            }],
            "limit": 0
        }
    )
    if result.total > 0:
        print(f"  {stage}: {result.total}")

Inputs to step 1: API token, HubSpot account with contacts and companies accessible.

Outputs from step 1: Count of contacts and companies by lifecycle stage; count of missing assignments. Document these numbers as your baseline.

---

Step 2: Define disallowed stages and correct mappings

Create a mapping table of stages you do not want in your database and their correct replacements. Example:

Disallowed Stage	Reason	Correct Stage
(empty/blank)	Invisible in reports	Lead
Subscriber	Misapplied to all contacts when intended for newsletter-only	Lead
Other	Meaningless catch-all	Lead
Evangelist	Rarely used correctly; conflicts with deal progression	Customer (if paying customer) or Lead

This is a decision table, not a mandate. Your mappings depend on your sales process, integrations, and current data. Review your stage distribution from Step 1 and decide what is correct for your organization.

Inputs to step 2: Business rules for lifecycle stages, current stage distribution report from Step 1.

Outputs from step 2: A finalized mapping of disallowed stage -> correct stage for use in Steps 3 and 4.

---

Step 3: Fix contacts at disallowed stages

Use the batch API to update contacts currently at disallowed stages. The critical rule: clear the lifecycle stage first (set to empty), then set the new value in a separate API call. Direct updates to an earlier stage are silently rejected by HubSpot.

# Pseudocode pattern for each disallowed stage:
# 1. Search for contacts with lifecyclestage == "disallowed_value"
# 2. Paginate through all results (do_search returns up to 100 per call, use after: param)
# 3. For each batch of up to 100 contacts:
#    a. Call batch update to clear lifecycle stage (set to "")
#    b. Call batch update to set lifecycle stage to correct_stage
# 4. Log successes and failures

DISALLOWED_MAPPINGS = {
    "subscriber": "lead",
    "other": "lead",
    "evangelist": "lead"
}

for disallowed_stage, correct_stage in DISALLOWED_MAPPINGS.items():
    # Example: search contacts with lifecyclestage == "subscriber"
    result = api_client.crm.contacts.search_api.do_search(
        public_object_search_request={
            "filterGroups": [{
                "filters": [{
                    "propertyName": "lifecyclestage",
                    "operator": "EQ",
                    "value": disallowed_stage
                }]
            }],
            "limit": 100,
            "after": None  # Paginate with after parameter
        }
    )
    
    for contact in result.results:
        contact_id = contact.id
        # Clear
        api_client.crm.contacts.basic_api.update(
            contact_id=contact_id,
            simple_public_object_input={"properties": {"lifecyclestage": ""}}
        )
        # Set
        api_client.crm.contacts.basic_api.update(
            contact_id=contact_id,
            simple_public_object_input={"properties": {"lifecyclestage": correct_stage}}
        )

Inputs to step 3: Disallowed stage mappings from Step 2, API token, HubSpot contacts.

Outputs from step 3: All contacts previously at disallowed stages are now at correct stages. Count of contacts moved per stage.

---

Step 4: Set missing contact stages using associated company context

Do not assign all missing-stage contacts to "Lead" blindly. Check their associated company first:

1. Search for contacts with no lifecycle stage assigned
2. For each contact, fetch its primary associated company
3. Check that company's lifecycle stage
4. Assign the contact's stage to match the company stage (or "lead" as default if company has no stage)

Context-aware assignment prevents downgrading a contact at a Customer company to "Lead".

# Pseudocode pattern:
# 1. Search contacts with lifecyclestage NOT_HAS_PROPERTY
# 2. For each contact:
#    a. Get associated company via associations API
#    b. Read company's lifecycle stage
#    c. If company stage is "customer", set contact to "customer"
#    d. If company stage is "opportunity", set contact to "opportunity"
#    e. Otherwise, set contact to "lead"

# Alternative UI approach:
# 1. In HubSpot, create list: Lifecycle stage is unknown AND Associated company > Lifecycle stage is "customer"
# 2. Bulk edit that list to set lifecycle stage = "customer"
# 3. Create list: Lifecycle stage is unknown AND Associated company > Lifecycle stage is "opportunity"
# 4. Bulk edit that list to set lifecycle stage = "opportunity"
# 5. Create list: Lifecycle stage is unknown (remaining)
# 6. Bulk edit to set lifecycle stage = "lead"

Inputs to step 4: Contacts with missing lifecycle stage, associated company data, mapping of company stage to contact stage.

Outputs from step 4: All contacts with missing stages now have stages assigned based on company context. Count of contacts assigned per stage.

---

Step 5: Fix companies without lifecycle stage

1. Search for companies with no lifecycle stage
2. For companies with closed-won deals, set lifecycle stage to "Customer"
3. For companies with open deals, set lifecycle stage to "Opportunity"
4. For remaining companies with no stage, set to "Lead"

# Pseudocode pattern:
# 1. Search companies with lifecyclestage NOT_HAS_PROPERTY
# 2. For each company:
#    a. Get associated deals via associations API
#    b. Check deal statuses
#    c. If any deal status == "Closed Won", set company stage to "customer"
#    d. If any deal status == "Open" (and no Closed Won), set to "opportunity"
#    e. Otherwise set to "lead"

# Alternative UI approach:
# 1. Create company list: Lifecycle stage is unknown AND Associated deal > Deal stage is "Closed Won"
# 2. Bulk edit to set lifecycle stage = "customer"
# 3. Create company list: Lifecycle stage is unknown AND Associated deal > Deal stage is not "Closed Won"
# 4. Bulk edit to set lifecycle stage = "opportunity"
# 5. Create company list: Lifecycle stage is unknown (remaining)
# 6. Bulk edit to set lifecycle stage = "lead"

Inputs to step 5: Companies with missing lifecycle stage, associated deal data, deal status definitions.

Outputs from step 5: All companies with missing stages now have stages assigned based on deal context. Count of companies assigned per stage.

---

Step 6: Fix stuck records

If any records still have incorrect lifecycle stages after Step 3 (likely due to forward-only progression rule or workflow delays), run a verification search and force-fix them using the clear-then-set pattern:

# Find contacts still at disallowed stages
for disallowed_stage in ["subscriber", "other", "evangelist"]:
    result = api_client.crm.contacts.search_api.do_search(
        public_object_search_request={
            "filterGroups": [{
                "filters": [{
                    "propertyName": "lifecyclestage",
                    "operator": "EQ",
                    "value": disallowed_stage
                }]
            }],
            "limit": 100
        }
    )
    
    if result.total > 0:
        print(f"WARNING: {result.total} contacts still at {disallowed_stage}")
        for contact in result.results:
            contact_id = contact.id
            # Clear then set
            api_client.crm.contacts.basic_api.update(
                contact_id=contact_id,
                simple_public_object_input={"properties": {"lifecyclestage": ""}}
            )
            api_client.crm.contacts.basic_api.update(
                contact_id=contact_id,
                simple_public_object_input={"properties": {"lifecyclestage": "lead"}}
            )

Inputs to step 6: Disallowed stage list, API token, HubSpot contacts.

Outputs from step 6: Count of stuck records found and fixed. Should be 0 if Steps 1-5 executed correctly.

---

Step 7: Create prevention workflows for contacts

In HubSpot Automation > Workflows, create a contact-based workflow:

1. Click Create workflow > Contact-based > Blank workflow
2. Name: AUTO-FIX: Set Default Lifecycle Stage (Lead)
3. Enrollment trigger: Contact property > Lifecycle stage > is unknown
4. Enable "re-enroll contacts" so new contacts entering this state get auto-fixed
5. Action: Set contact property > Lifecycle stage > Lead
6. Activate workflow
7. Manually enroll all existing contacts in the workflow (bulk action)

This workflow fires whenever a contact's lifecycle stage becomes empty and automatically sets it to "Lead".

Inputs to step 7: HubSpot Automation access, contact list.

Outputs from step 7: Active workflow that auto-assigns lifecycle stage to contacts.

---

Step 8: Create prevention workflows for companies

In HubSpot Automation > Workflows, create a company-based workflow:

1. Click Create workflow > Company-based > Blank workflow
2. Name: AUTO-FIX: Set Default Company Lifecycle Stage (Lead)
3. Enrollment trigger: Company property > Lifecycle stage > is unknown
4. Enable "re-enroll contacts"
5. Action: Set company property > Lifecycle stage > Lead
6. Activate workflow
7. Manually enroll all existing companies in the workflow

This workflow fires whenever a company's lifecycle stage becomes empty and automatically sets it to "Lead".

Inputs to step 8: HubSpot Automation access, company list.

Outputs from step 8: Active workflow that auto-assigns lifecycle stage to companies.

---

Step 9 (optional): Create disallowed stage correction workflows

If your data imports or integrations keep re-creating disallowed stages (e.g., contacts keep getting set to "Subscriber"), create additional workflows to catch and fix them immediately:

1. Click Create workflow > Contact-based > Blank workflow
2. Name: AUTO-FIX: Correct Disallowed Lifecycle Stages
3. Enrollment trigger: Lifecycle stage > changed to "Subscriber" (or other disallowed value)
4. Enable "re-enroll contacts"
5. Action 1: Clear property > Lifecycle stage (set to blank)
6. Action 2: Set contact property > Lifecycle stage > Lead (or correct mapped stage)
7. Activate workflow

Repeat for each disallowed stage. This prevents disallowed stages from persisting.

Inputs to step 9: Disallowed stage list, HubSpot Automation access.

Outputs from step 9: Workflows that immediately correct disallowed stages when they appear.

---

Step 10: Verify 100% coverage

Re-run the audit script from Step 1 and confirm:

# Contacts with missing lifecycle stage should be 0
result = api_client.crm.contacts.search_api.do_search(
    public_object_search_request={
        "filterGroups": [{
            "filters": [{
                "propertyName": "lifecyclestage",
                "operator": "NOT_HAS_PROPERTY"
            }]
        }],
        "limit": 0
    }
)
print(f"Contacts missing lifecycle stage: {result.total} (should be 0)")

# Companies with missing lifecycle stage should be 0
result = api_client.crm.companies.search_api.do_search(
    public_object_search_request={
        "filterGroups": [{
            "filters": [{
                "propertyName": "lifecyclestage",
                "operator": "NOT_HAS_PROPERTY"
            }]
        }],
        "limit": 0
    }
)
print(f"Companies missing lifecycle stage: {result.total} (should be 0)")

# Spot-check: no contacts at disallowed stages
for disallowed_stage in ["subscriber", "other", "evangelist"]:
    result = api_client.crm.contacts.search_api.do_search(
        public_object_search_request={
            "filterGroups": [{
                "filters": [{
                    "propertyName": "lifecyclestage",
                    "operator": "EQ",
                    "value": disallowed_stage
                }]
            }],
            "limit": 0
        }
    )
    if result.total > 0:
        print(f"ERROR: {result.total} contacts still at {disallowed_stage}")

Inputs to step 10: API token, HubSpot account.

Outputs from step 10: Verification report confirming 0 missing assignments and 0 disallowed stages.

---

decision points

Decision: Which stages are disallowed for your organization?

• If your business uses a strict stage progression (Subscriber > Lead > MQL > SQL > Opportunity > Customer > Evangelist) with no deviation, mark "Subscriber", "Other", and "Evangelist" as disallowed and map them to "Lead".
• If your organization allows exceptions (e.g., "Evangelist" is a real segment), do not mark it as disallowed. Define only the stages that genuinely have no place in your data.

Decision: How should context-aware assignment work for contacts?

• If a contact is at a company with lifecycle stage "Customer", assign the contact to "Customer" (Step