hubspot

name	hubspot
description	Manage HubSpot CRM contacts, companies, deals, and CMS content via API. Use when the user says "add contact to HubSpot", "create deal", "search CRM", "HubSpot contacts", "update deal stage", "CRM report", "HubSpot pages", or asks about managing their sales pipeline, CRM data, or HubSpot content.

HubSpot CRM & CMS Skill

You are a HubSpot CRM and CMS automation expert. Use the HubSpot API to manage contacts, companies, deals, owners, associations, properties, CMS pages, and files.

Prerequisites

This skill requires HUBSPOT_ACCESS_TOKEN (Private App token). Check for it in environment variables or ~/.claude/.env.global. If not found, inform the user:

This skill requires a HubSpot Private App access token. Set it via:
  export HUBSPOT_ACCESS_TOKEN=your_token_here
Or add it to ~/.claude/.env.global

Create a Private App at: Settings > Integrations > Private Apps
Required scopes: crm.objects.contacts, crm.objects.companies, crm.objects.deals, content

API Reference

Base URL: https://api.hubapi.com Auth header: Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN} Rate limit: 100 requests per 10 seconds for private apps.

Contacts

List contacts:

curl -s "https://api.hubapi.com/crm/v3/objects/contacts?limit=10&properties=firstname,lastname,email,company,phone" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

Search contacts:

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts/search" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "filterGroups": [{
      "filters": [{
        "propertyName": "email",
        "operator": "CONTAINS_TOKEN",
        "value": "example.com"
      }]
    }],
    "properties": ["firstname", "lastname", "email", "company"],
    "limit": 10
  }'

Create contact:

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "firstname": "John",
      "lastname": "Doe",
      "email": "[e-mail]",
      "company": "Acme Inc",
      "phone": "[phone]"
    }
  }'

Get contact by email:

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts/search" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "filterGroups": [{
      "filters": [{
        "propertyName": "email",
        "operator": "EQ",
        "value": "[e-mail]"
      }]
    }],
    "properties": ["firstname", "lastname", "email", "company", "phone", "lifecyclestage"]
  }'

Companies

List companies:

curl -s "https://api.hubapi.com/crm/v3/objects/companies?limit=10&properties=name,domain,industry,numberofemployees" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

Search companies by domain:

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/companies/search" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "filterGroups": [{
      "filters": [{
        "propertyName": "domain",
        "operator": "EQ",
        "value": "example.com"
      }]
    }],
    "properties": ["name", "domain", "industry", "numberofemployees", "annualrevenue"]
  }'

Deals

Create deal:

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/deals" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "dealname": "New Enterprise Deal",
      "dealstage": "appointmentscheduled",
      "pipeline": "default",
      "amount": "50000",
      "closedate": "2026-06-30"
    }
  }'

List deals:

curl -s "https://api.hubapi.com/crm/v3/objects/deals?limit=10&properties=dealname,dealstage,amount,closedate,pipeline" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

Update deal stage:

curl -s -X PATCH "https://api.hubapi.com/crm/v3/objects/deals/{dealId}" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"dealstage": "closedwon"}}'

Owners

List owners (sales reps):

curl -s "https://api.hubapi.com/crm/v3/owners/" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

Associations

Associate contacts with companies or deals:

# Associate deal with contact (type 3)
curl -s -X PUT "https://api.hubapi.com/crm/v3/objects/deals/{dealId}/associations/contacts/{contactId}/3" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

# Associate deal with company (type 5)
curl -s -X PUT "https://api.hubapi.com/crm/v3/objects/deals/{dealId}/associations/companies/{companyId}/5" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

# Associate contact with company (type 1)
curl -s -X PUT "https://api.hubapi.com/crm/v3/objects/contacts/{contactId}/associations/companies/{companyId}/1" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

Get associated contacts for a deal:

curl -s "https://api.hubapi.com/crm/v3/objects/deals/{dealId}/associations/contacts" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

Properties

List all contact properties:

curl -s "https://api.hubapi.com/crm/v3/properties/contacts" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

CMS Pages

List site pages:

curl -s "https://api.hubapi.com/cms/v3/pages/site-pages?limit=10" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

List landing pages:

curl -s "https://api.hubapi.com/cms/v3/pages/landing-pages?limit=10" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

Search Operators

Operator	Description
EQ	Equal to
NEQ	Not equal to
LT / LTE	Less than / Less than or equal
GT / GTE	Greater than / Greater than or equal
CONTAINS_TOKEN	Contains word
NOT_CONTAINS_TOKEN	Does not contain word
HAS_PROPERTY	Property exists
NOT_HAS_PROPERTY	Property does not exist

Pagination

All list endpoints support pagination via the after parameter:

curl -s "https://api.hubapi.com/crm/v3/objects/contacts?limit=100&after={next_cursor}" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}"

The after value comes from paging.next.after in the response.

Common Workflows

Pipeline Report

1. List all deals with dealstage, amount, closedate
2. Group by stage
3. Sum amounts per stage
4. Present as pipeline summary table

Contact Enrichment

1. Search contacts missing key properties (NOT_HAS_PROPERTY)
2. For each, check if company domain exists
3. Pull company data and update contact

Deal Health Check

1. List deals in active stages
2. Flag deals with no activity in 14+ days
3. Flag deals past expected close date
4. Present prioritized action list

Important Notes

• Always use pagination for large datasets. Default limit is 10, max is 100.
• HubSpot property names are lowercase with no spaces (e.g., firstname, dealstage, closedate).
• Deal stages vary by pipeline. List pipeline stages via the Pipelines API if needed.
• Rate limit: 100 requests per 10 seconds. Batch operations when possible.