hubspot-lifecycle-and-lists

What this skill does

# HubSpot Lifecycle and Lists

## Overview

Move contacts through the HubSpot funnel and maintain list integrity in a production system. This is not a setup walkthrough — it is the code your marketing-ops integration runs when a lifecycle stage update would silently regress a Customer back to Subscriber, when a dynamic list's criteria change orphans members who qualified last week, when a static list import references contacts that were deleted from the portal, when an external lead-scoring model creates a second source of truth that fights HubSpot's native scoring, when a list-membership webhook fires but your consumer returns 5xx and HubSpot never retries, and when an agency needs to mirror list membership across two portals that have no native sync API.

The six production failures this skill prevents:

1. **Lifecycle stage regression** — HubSpot's `PATCH /crm/v3/objects/contacts/{id}` will set lifecyclestage to any valid value regardless of direction. Setting a Customer back to Subscriber silently destroys funnel attribution, invalidates reporting, and corrupts revenue forecasting. The API returns `200 OK`. There is no built-in guard.
2. **Dynamic list criteria drift** — editing a dynamic list's filter criteria does not immediately re-evaluate existing members against the new rules. Members who no longer qualify remain in the list until the nightly background refresh completes, creating a stale membership window of up to 24 hours that can trigger incorrect nurture emails or suppression failures.
3. **Static list import orphans** — contacts added to a static list via import or `POST /contacts/v1/lists/{listId}/add` remain list members even after the underlying contact record is hard-deleted from the CRM. These orphan IDs return errors on any subsequent contact-level API call and pollute downstream sync pipelines.
4. **Lead scoring model disagreement** — writing an external score to a custom contact property while HubSpot's native Lead Scoring tool computes its own score creates two competing signals. Sales works from the HubSpot Score field; marketing automation triggers on the custom property. The two scores diverge and nobody knows which one to trust.
5. **List-membership webhook missed events** — HubSpot's webhook system delivers `contact.propertyChange` events for lifecyclestage updates and list-membership changes via HTTP POST with no retry on 5xx responses. A single downstream outage during a bulk-import window can drop hundreds of membership events permanently with no dead-letter queue or re-delivery mechanism.
6. **Cross-portal list sync** — agencies managing multiple HubSpot portals (e.g., a staging portal mirroring a production portal, or two franchisee portals needing shared suppression lists) have no native API to sync list membership between portals. Manual export-import lags by hours and has no idempotency guarantee.

## Prerequisites

- HubSpot account with a private app token scoped to:
  - `crm.objects.contacts.read`
  - `crm.objects.contacts.write`
  - `crm.lists.read`
  - `crm.lists.write`
  - `crm.schemas.contacts.read` (for lifecycle stage enumeration)
- Python 3.10+ or Node.js 18+ for implementation examples
- `jq` on PATH for shell-level inspection
- `curl` for API verification steps
- For webhook consumption: an HTTPS endpoint reachable by HubSpot's webhook delivery infrastructure
- For cross-portal sync: private app tokens for both portals stored in separate environment variables or a credential router (see `hubspot-auth` skill)

Store all tokens in a secret manager. Never put `pat-na1-*` values in source code or committed `.env` files.

## Instructions

Build in this order. Each section neutralizes one production failure mode.

### 1. Lifecycle stage progression guard (neutralizes regression)

The lifecycle stage enum has a defined forward direction. Any update that moves a contact backward is almost certainly a data pipeline bug, not an intentional business action.

Canonical stage order (HubSpot internal values, not display labels):

```
subscriber → lead → marketingqualifiedlead → salesqualifiedlead → opportunity → customer → evangelist → other
```

`other` is a lateral bucket, not a terminal stage — it sits outside the linear progression and should only be set explicitly.

Never read the stage order from display labels. Display labels are portal-configurable. Always use the internal enum values.

**Progression guard pattern (Python):**

```python
STAGE_ORDER = [
    "subscriber",
    "lead",
    "marketingqualifiedlead",
    "salesqualifiedlead",
    "opportunity",
    "customer",
    "evangelist",
]
# 'other' is not in the linear sequence — treat as a lateral assignment

def stage_index(stage: str) -> int:
    try:
        return STAGE_ORDER.index(stage.lower())
    except ValueError:
        return -1  # 'other' or unknown — always allow

def safe_set_lifecycle(contact_id: str, new_stage: str, token: str) -> dict:
    current = get_contact_lifecycle(contact_id, token)
    current_idx = stage_index(current)
    new_idx = stage_index(new_stage)

    # Allow lateral 'other' assignments and forward progressions
    if current_idx != -1 and new_idx != -1 and new_idx < current_idx:
        raise ValueError(
            f"Lifecycle regression blocked: {current} → {new_stage} "
            f"for contact {contact_id}. "
            f"Current index={current_idx}, requested index={new_idx}."
        )

    return patch_contact_lifecycle(contact_id, new_stage, token)

def get_contact_lifecycle(contact_id: str, token: str) -> str:
    import urllib.request, json
    url = f"https://api.hubapi.com/crm/v3/objects/contacts/{contact_id}?properties=lifecyclestage"
    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
    with urllib.request.urlopen(req) as resp:
        data = json.loads(resp.read())
    return data["properties"].get("lifecyclestage", "subscriber")

def patch_contact_lifecycle(contact_id: str, stage: str, token: str) -> dict:
    import urllib.request, json
    url = f"https://api.hubapi.com/crm/v3/objects/contacts/{contact_id}"
    payload = json.dumps({"properties": {"lifecyclestage": stage}}).encode()
    req = urllib.request.Request(
        url,
        data=payload,
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
        },
        method="PATCH",
    )
    with urllib.request.urlopen(req) as resp:
        return json.loads(resp.read())
```

Verify a contact's current stage before running a bulk update:

```bash
curl -s \
  "https://api.hubapi.com/crm/v3/objects/contacts/{contact-id}?properties=lifecyclestage" \
  -H "Authorization: Bearer {your-token}" \
  | jq '.properties.lifecyclestage'
```

### 2. Dynamic list criteria drift (neutralizes stale membership)

When you edit a dynamic list's filter criteria, HubSpot queues a background re-evaluation job. Existing members who no longer satisfy the new criteria remain in the list until that job completes — up to 24 hours. Any automation triggered on list membership during that window operates on stale data.

**Production pattern: snapshot membership before and after a criteria change, then audit the delta.**

```python
import urllib.request, json, time

def snapshot_list_members(list_id: int, token: str) -> set[str]:
    """Return the full set of vid (legacy contact ID) strings for a list."""
    vids = set()
    offset = None
    while True:
        url = f"https://api.hubapi.com/contacts/v1/lists/{list_id}/contacts/all?count=100"
        if offset:
            url += f"&vidOffset={offset}"
        req = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
        with urllib.request.urlopen(req) as resp:
            data = json.loads(resp.read())
        for contact in data.get("contacts", []):
            vids.add(str(contact["vid"]))
        if not data.get("has-more", False):
            break
        offset = data["vid-offset"]
    return