hubspot

name	hubspot
version	1.0.0
description	HubSpot CRM and CMS API integration for contacts, companies, deals, owners, and content management.
author	G-HunterAi
license	MIT
tags	["crm","hubspot","contacts","deals","marketing"]
platforms	["all"]
category	integration
emoji	🟠
metadata	{"clawdbot":{"secrets":["HUBSPOT_ACCESS_TOKEN"]}}

HubSpot Skill

Enterprise CRM integration for managing contacts, companies, deals, and content via HubSpot's REST API.

When to Use

• Managing enterprise CRM contacts, companies, and deals
• Syncing customer data from external systems
• Running CRM workflows and automations
• Tracking sales pipelines and deal progression
• Managing CMS pages and landing pages
• File management and asset libraries

When NOT to Use

• Personal contact management (use people-memories skill instead)
• Self-hosted CRM systems (use twenty-crm skill)
• Marketing automation beyond CRM scope (use dedicated tools)

Prerequisites

1. HubSpot Account — Enterprise or Professional tier
2. Private App Access Token — Create at https://app.hubspot.com/l/private-apps
3. Required Scopes — contacts, companies, deals, crm.objects.owners.read

Set environment variable:

export HUBSPOT_ACCESS_TOKEN=pat-na2-xxxxx

Setup

Set your HubSpot Private App access token:

HUBSPOT_ACCESS_TOKEN=pat-na2-xxxxx

API Base

All endpoints use: https://api.hubapi.com

Authorization header: Bearer $HUBSPOT_ACCESS_TOKEN

---

CRM Objects

Contacts

Create contact:

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

List contacts:

curl -s -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  "https://api.hubapi.com/crm/v3/objects/contacts?limit=10" | jq

Search contacts:

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

Get contact by ID:

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

Get contact by email:

curl -s -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  "https://api.hubapi.com/crm/v3/objects/contacts/{email}?idProperty=email" | jq

Companies

List companies:

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

Search companies:

curl -s -X POST -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filterGroups":[{"filters":[{"propertyName":"name","operator":"CONTAINS_TOKEN","value":"acme"}]}],"limit":10}' \
  "https://api.hubapi.com/crm/v3/objects/companies/search" | jq

Get company by ID:

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

Deals

Create deal:

curl -s -X POST -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"properties":{"dealname":"New Deal","amount":"10000","closedate":"2026-06-01","description":"Deal notes here"}}' \
  "https://api.hubapi.com/crm/v3/objects/deals" | jq

List deals:

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

Search deals:

curl -s -X POST -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filterGroups":[{"filters":[{"propertyName":"dealstage","operator":"EQ","value":"closedwon"}]}],"limit":10}' \
  "https://api.hubapi.com/crm/v3/objects/deals/search" | jq

Get deal by ID:

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

Owners

List owners (users):

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

---

Update & Assign Owner

Update contact properties:

curl -s -X PATCH -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"properties":{"phone":"555-9999","jobtitle":"Director"}}' \
  "https://api.hubapi.com/crm/v3/objects/contacts/{contactId}" | jq

Assign owner to contact:

curl -s -X PATCH -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"properties":{"hubspot_owner_id":"{ownerId}"}}' \
  "https://api.hubapi.com/crm/v3/objects/contacts/{contactId}" | jq

Assign owner to deal:

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

---

Associations

Get associated contacts for a company:

curl -s -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  "https://api.hubapi.com/crm/v4/objects/companies/{companyId}/associations/contacts" | jq

Get associated deals for a contact:

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

Create association (deal to contact):

curl -s -X POST -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs":[{"from":{"id":"{dealId}"},"to":{"id":"{contactId}"},"types":[{"associationCategory":"HUBSPOT_DEFINED","associationTypeId":3}]}]}' \
  "https://api.hubapi.com/crm/v4/associations/deals/contacts/batch/create" | jq

Common association type IDs:

• 3: Deal to Contact
• 5: Deal to Company
• 1: Contact to Company

---

Properties (Schema)

List contact properties:

curl -s -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  "https://api.hubapi.com/crm/v3/properties/contacts" | jq '.results[].name'

List company properties:

curl -s -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  "https://api.hubapi.com/crm/v3/properties/companies" | jq '.results[].name'

List deal properties:

curl -s -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  "https://api.hubapi.com/crm/v3/properties/deals" | jq '.results[].name'

---

CMS

Pages

List site pages:

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

List landing pages:

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

Domains

List domains:

curl -s -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  "https://api.hubapi.com/cms/v3/domains" | jq

---

Files

List files:

curl -s -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  "https://api.hubapi.com/files/v3/files?limit=10" | jq

Search files:

curl -s -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" \
  "https://api.hubapi.com/files/v3/files/search?name=logo" | jq

---

Search Operators

For search endpoints, use these operators in filters:

Operator	Description
EQ	Equal to
NEQ	Not equal to
LT	Less than
LTE	Less than or equal
GT	Greater than
GTE	Greater than or equal
CONTAINS_TOKEN	Contains word
NOT_CONTAINS_TOKEN	Does not contain word
HAS_PROPERTY	Has a value
NOT_HAS_PROPERTY	Does not have a value

---

PowerShell Examples

For Windows/PowerShell, use Invoke-RestMethod:

$headers = @{
  "Authorization" = "Bearer $env:HUBSPOT_ACCESS_TOKEN"
  "Content-Type" = "application/json"
}

# List contacts
Invoke-RestMethod -Uri "https://api.hubapi.com/crm/v3/objects/contacts?limit=10" -Headers $headers

# Search contacts
$body = @{
  filterGroups = @(@{
    filters = @(@{
      propertyName = "email"
      operator = "CONTAINS_TOKEN"
      value = "example.com"
    })
  })
  limit = 10
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Method POST -Uri "https://api.hubapi.com/crm/v3/objects/contacts/search" -Headers $headers -Body $body

---

Error Handling

Status Code	Meaning	Recovery
400	Bad request	Validate JSON structure and required fields
401	Unauthorized	Check HUBSPOT_ACCESS_TOKEN is set and valid
403	Forbidden	Verify private app has required scopes
404	Not found	Confirm object ID and endpoint path
429	Rate limited	Wait and retry; limits are 100 req/10sec for private apps
500	Server error	Retry with exponential backoff

---

Works Well With

• quickbooks — Sync customer data between HubSpot and QuickBooks
• people-memories — Store personal contacts not in CRM
• email-automation — Trigger workflows from CRM data
• workflow-orchestrator — Complex multi-step CRM processes

---

Notes

• Full CRUD operations supported with appropriate scopes
• Rate limits: 100 requests per 10 seconds for private apps
• Pagination: Use after parameter from paging.next.after for next page
• Portal ID is in the record URL: https://app-na2.hubspot.com/contacts/{portalId}/record/...