hubspot

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: hubspot
description: "Read HubSpot contacts, companies, and deals; update deal stages and lifecycle stages; log notes and tasks through gateway-managed bearer tokens."
user-invocable: true
requires:
  bins:
    - node
credentials:
  - id: hubspot-access-token
    kind: bearer
    required: true
    secret_ref:
      source: store
      id: HUBSPOT_ACCESS_TOKEN
    scope: "api.hubapi.com and api.hubspot.com"
    how_to_obtain: "Create a HubSpot Service Key from Development > Keys > Service keys and copy the key. Set `HUBSPOT_ACCESS_TOKEN` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set HUBSPOT_ACCESS_TOKEN <token>` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set HUBSPOT_ACCESS_TOKEN <token>`. Service keys are the recommended single-account system-to-system credential for HubSpot REST APIs. Legacy private app access tokens and OAuth access tokens are also accepted bearer credentials; HubSpot personal access keys and developer keys are not valid CRM REST bearer tokens."
metadata:
  hybridclaw:
    category: business
    short_description: "HubSpot CRM reads and guarded writes."
    tags:
      - hubspot
      - crm
      - contacts
      - companies
      - deals
      - service-key
      - private-app-token
      - oauth
    stakes_tiers:
      green:
        - contact-read
        - company-read
        - deal-read
        - property-read
      amber:
        - deal-stage-update
        - lifecycle-stage-update
        - note-create
        - task-create
    escalation:
      writes: confirm-each
      route: f14
    cost_measurement:
      system: UsageTotals
      sub_limit_key: hubspot
---

# HubSpot

Use this skill for HubSpot CRM work when the operator has connected HubSpot to
HybridClaw with a HubSpot Service Key, legacy private app access token, or
OAuth credentials.

## Scope

- read contacts, companies, and deals
- search high-frequency CRM objects by common properties
- inspect HubSpot CRM properties for contacts, companies, and deals
- update a deal's `dealstage`
- update contact, company, or deal `lifecyclestage`
- create timeline notes associated with contacts, companies, or deals
- create tasks associated with contacts, companies, or deals
- plan common natural-language CRM requests before building API calls
- build ordered natural-language workflows with lookup, property-validation, and
  write steps for the high-frequency CRM operations
- validate internal HubSpot stage option values from saved property metadata
- interpret common HubSpot authentication, authorization, stage, and rate-limit
  errors
- measure cost per assistant run through normal HybridClaw `UsageTotals`

## Credential Rules

For normal single-account HubSpot use, create a HubSpot Service Key and store
it as `HUBSPOT_ACCESS_TOKEN` in HybridClaw encrypted runtime secrets. Service
Keys are HubSpot's recommended account-level, system-to-system bearer
credential for direct REST API requests when OAuth and webhooks are not needed.
Never paste tokens into a prompt.

Create the Service Key in HubSpot under **Development > Keys > Service keys**
or open <https://app.hubspot.com/service-keys>. Give it only the scopes needed
for the requested CRM operations, copy the key, and store that value as
`HUBSPOT_ACCESS_TOKEN`. Do not use a HubSpot Personal Access Key or Developer
Key for this skill; those are for other HubSpot developer workflows and are not
valid CRM REST bearer tokens for these calls.
HubSpot Service Key docs:
<https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/account-service-keys>.

Recommended setup order:

1. Browser admin: open the active HybridClaw admin URL ending in `/admin/secrets` and set
   `HUBSPOT_ACCESS_TOKEN`.
2. Browser `/chat` or TUI fallback:
   `/secret set HUBSPOT_ACCESS_TOKEN <token>`.
3. Local console fallback:

```bash
hybridclaw secret set HUBSPOT_ACCESS_TOKEN
```

Equivalent setup when pass