hubspot

HubSpot CRM & Marketing AI Skill Guide

Overview & Engine Architecture

HubSpot unifies CRM (contacts, companies, deals, tickets), marketing automation, and a REST API. Properties define fields; workflows and pipelines move records through stages. Private apps replace legacy API keys with scoped tokens. Agents design clear property taxonomies, idempotent syncs, and workflow rules that do not thrash records.

Portals
   -> CRM objects (contacts, companies, deals, tickets, custom)
       -> Properties + associations
       -> Pipelines / workflows / lists
Integrations -> Private app tokens -> HubSpot APIs (CRM, CMS, Events)

When to use this skill

• Modeling deal pipelines and contact lifecycle stages
• Building HubSpot workflows without loops
• Syncing product/user data via the CRM API
• Debugging association and property mismatches

Operational directives

1. Use private apps with least-privilege scopes; rotate tokens on staff changes.
2. Prefer association APIs over stuffing foreign keys into free-text properties.
3. Workflows: enrollment criteria must exclude already-processed records; watch re-enrollment.
4. Respect rate limits; batch reads/writes and backoff on 429.
5. Do not use marketing emails as a substitute for transactional product mail without compliance review.

CRM API sketch

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts/batch/upsert" \
  -H "Authorization: Bearer $HUBSPOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{
      "idProperty": "email",
      "id": "[email protected]",
      "properties": { "firstname": "Ada", "lifecyclestage": "lead" }
    }]
  }'

Workflow hygiene

Smell	Better approach
Workflow updates property that re-enrolls same workflow	Exclude that property from re-enrollment triggers
Dozens of near-duplicate properties	One canonical property + clear naming convention
Sync writes every field every time	Patch only changed properties; store last sync hash
Shared super-admin private app	Split apps by system (billing vs support vs marketing)