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:

hybridclaw secret set HUBSPOT_ACCESS_TOKEN

Equivalent setup when passing the Service Key explicitly:

hybridclaw auth login hubspot \
  --access-token "<hubspot-service-key>" \
  --account sales@example.com

Legacy private app access tokens can also be stored as HUBSPOT_ACCESS_TOKEN, but new single-account REST integrations should prefer Service Keys.

OAuth client credentials are also supported for public app installations:

hybridclaw auth login hubspot \
  --client-id "<hubspot-oauth-client-id>" \
  --client-secret "<hubspot-oauth-client-secret>" \
  --refresh-token "<refresh-token>"

The gateway injects HUBSPOT_ACCESS_TOKEN only when an http_request uses bearerSecretName: "HUBSPOT_ACCESS_TOKEN" against HubSpot API hosts. With OAuth credentials, the gateway mints the access token from HUBSPOT_CLIENT_SECRET and HUBSPOT_REFRESH_TOKEN; with Service Key or legacy private app setup, the stored bearer credential is used directly.

Required HubSpot scopes depend on the task. The default OAuth login scope set covers contacts, companies, deals, notes, tasks, CRM schema reads, and oauth.

Default Workflow

1. Start with reads or plan. Do not mutate CRM state unless the user clearly asks for the exact write.
2. Run the bundled helper to build an http_request wrapper:

   node skills/hubspot/hubspot.cjs ...
   

3. Pass only the emitted httpRequest object to the built-in http_request tool when dry-running or when the helper cannot reach the gateway. For live HubSpot reads and writes, use the helper run command so the CJS script owns request construction, gateway submission, and auth-error handling.
4. Never handcraft HubSpot http_request calls from memory. The helper owns endpoint selection, method, payload, secret refs, and auth-error handling.
5. For natural-language writes, run workflow first. It emits ordered property metadata, lookup, operator confirmation, and write steps.
6. For writes, confirm the target record and intended field change, then pass either the exact --grant value or --operator-grant.
7. Use internal HubSpot IDs for write targets. If a name search returns multiple records, stop and ask for the exact record ID.
8. Use internal stage values for dealstage, pipeline, and lifecyclestage. Read /crm/v3/properties/... first when the internal value is unknown.
9. If a live HubSpot call returns 401 or 403, stop after that first failure. Do not retry, do not call more HubSpot endpoints, and do not guess from dates or epoch timestamps. Tell the operator to verify or replace HUBSPOT_ACCESS_TOKEN. For Service Keys, they should copy the current key from HubSpot's Service keys page or rotate it if HubSpot says it was revoked, expired, exposed, or invalid.

Command Contract

Plan a request without authentication:

node skills/hubspot/hubspot.cjs --format json plan "Move the Acme Renewal deal to contractsent and add a follow-up task"

Build an ordered natural-language workflow:

node skills/hubspot/hubspot.cjs --format json workflow \
  "Move the Acme Renewal deal to contractsent and log a note saying 'Contract sent to legal'"

After selecting the exact deal id from search results, rerun with the record id and exact grant:

node skills/hubspot/hubspot.cjs --format json workflow \
  "Move the Acme Renewal deal to contractsent" \
  --record-id 123456 \
  --grant approve-hubspot-deal-stage-update

Run live read requests:

node skills/hubspot/hubspot.cjs --format json run search contacts --query jane@example.com
node skills/hubspot/hubspot.cjs --format json run search companies --query acme
node skills/hubspot/hubspot.cjs --format json run search deals --query renewal

Build dry-run request payloads without calling HubSpot:

node skills/hubspot/hubspot.cjs --format json http-request list contacts --limit 25
node skills/hubspot/hubspot.cjs --format json http-request list companies --property name --property domain
node skills/hubspot/hubspot.cjs --format json http-request list deals --properties dealname,dealstage,pipeline,amount

Read a record or properties:

node skills/hubspot/hubspot.cjs --format json http-request get deals 123456 --associations contacts,companies
node skills/hubspot/hubspot.cjs --format json http-request properties deals
node skills/hubspot/hubspot.cjs --format json http-request properties contacts

Update a deal stage after explicit grant:

node skills/hubspot/hubspot.cjs --format json http-request update-deal-stage 123456 \
  --stage contractsent \
  --properties-file /tmp/hubspot-deal-properties.json \
  --grant approve-hubspot-deal-stage-update

Update lifecycle stage after explicit grant:

node skills/hubspot/hubspot.cjs --format json http-request update-lifecycle-stage contacts 123456 \
  --stage marketingqualifiedlead \
  --properties-file /tmp/hubspot-contact-properties.json \
  --grant approve-hubspot-lifecycle-stage-update

Validate an internal option value from a saved properties response:

node skills/hubspot/hubspot.cjs --format json validate-option \
  --properties-file /tmp/hubspot-deal-properties.json \
  --property dealstage \
  --value contractsent

Create a note associated with a deal:

node skills/hubspot/hubspot.cjs --format json http-request create-note \
  --body "Spoke with Carla about legal review." \
  --associate-object deals \
  --associate-id 123456 \
  --grant approve-hubspot-note-create

Create a task associated with a contact:

node skills/hubspot/hubspot.cjs --format json http-request create-task \
  --subject "Send procurement packet" \
  --body "Follow up with pricing and security documentation." \
  --due 2026-05-20 \
  --associate-object contacts \
  --associate-id 987654 \
  --grant approve-hubspot-task-create

Run the offline eval suite:

node skills/hubspot/hubspot.cjs --format json eval-scenarios

Explain a HubSpot API error wrapper:

node skills/hubspot/hubspot.cjs --format json explain-error \
  --status 403 \
  --body '{"message":"missing scope crm.objects.deals.write"}'

Working Rules

• Use http_request; do not use curl for HubSpot API calls when http_request is available.
• Never print, store in files, or include real HubSpot access tokens in tool arguments or prose.
• Never infer that a HubSpot token is a "default", "stale", or "1970" value from API timestamps. HubSpot Service Keys, legacy private app tokens, and OAuth tokens are opaque; report only that the stored HUBSPOT_ACCESS_TOKEN was rejected and needs verification or replacement.
• Treat writes as amber operations and require exact operator grant in the current task.
• Use exact HubSpot record IDs for writes.
• Use HubSpot internal option values, not labels, for dealstage, pipeline, and lifecyclestage.
• Read CRM properties before changing a stage when the internal value is not known.
• Prefer passing saved property metadata with --properties-file for dealstage and lifecyclestage writes so the helper validates internal option values before emitting a write request.
• HubSpot lifecycle stage changes can be constrained by HubSpot's lifecycle ordering rules; if the API rejects a backwards move, report the upstream constraint instead of retrying with guessed values.
• Cost per assistant run is recorded by HybridClaw UsageTotals; helper output includes costMeasurement.system = "UsageTotals" so evals can verify the accounting contract.

Eval Suite

The fixture at evals/scenarios.json contains 30 representative scenarios across contact/company/deal reads, deal stage updates, lifecycle updates, note logging, task creation, and compound requests.

Validation

Run:

node skills/hubspot/hubspot.cjs --help
node skills/hubspot/hubspot.cjs --format json eval-scenarios