hubspot-api

name	hubspot-api
description	Access HubSpot CRM API for deals, contacts, companies, and engagements. Covers PAT auth, deal pipeline queries, contact search, and Supabase ingest. Use when: querying CRM data, checking deal status, enriching contacts, syncing to PIL. Skip when: data already in PIL ontology (check there first).

HubSpot API

[!IMPORTANT] GFV-Adapted Skill — This skill runs within the GetFresh Ventures infrastructure.

GFV Infrastructure Integration

Credentials:

# Private App Token (PAT)
security find-generic-password -s "HUBSPOT_API_KEY" -w

Data Sources — Check PIL FIRST before hitting HubSpot API:

• search_pil / get_entity MCP tools — 81K entities, many from HubSpot
• Supabase entity_embeddings where source = 'hubspot'
• ont_entities and ont_facts for relationship data

---

Overview

Queries HubSpot CRM via REST API using a Private App Token (PAT). Covers deals, contacts, companies, and engagements. All data synced to Supabase via PIL ingest pipeline.

Authentication

# All requests use Bearer token
HUBSPOT_API_KEY=$(security find-generic-password -s "HUBSPOT_API_KEY" -w)

curl -s "https://api.hubapi.com/crm/v3/objects/deals" \
  -H "Authorization: Bearer $HUBSPOT_API_KEY" \
  -H "Content-Type: application/json"

Core Endpoints

Deals

# List all deals
GET /crm/v3/objects/deals
  ?properties=dealname,amount,closedate,dealstage,pipeline
  &limit=100

# Get single deal
GET /crm/v3/objects/deals/{dealId}
  ?properties=dealname,amount,closedate,dealstage,pipeline,hubspot_owner_id

# Search deals by name
POST /crm/v3/objects/deals/search
{
  "filterGroups": [{
    "filters": [{
      "propertyName": "dealname",
      "operator": "CONTAINS_TOKEN",
      "value": "Acme Corp"
    }]
  }],
  "properties": ["dealname", "amount", "dealstage", "closedate"]
}

Contacts

# Search contacts by email
POST /crm/v3/objects/contacts/search
{
  "filterGroups": [{
    "filters": [{
      "propertyName": "email",
      "operator": "EQ",
    }]
  }],
  "properties": ["email", "firstname", "lastname", "phone", "company"]
}

# Get contact with associations
GET /crm/v3/objects/contacts/{contactId}
  ?associations=deals,companies

Companies

# Search companies
POST /crm/v3/objects/companies/search
{
  "filterGroups": [{
    "filters": [{
      "propertyName": "name",
      "operator": "CONTAINS_TOKEN",
      "value": "Acme Corp"
    }]
  }],
  "properties": ["name", "domain", "industry", "numberofemployees"]
}

Engagements (emails, calls, meetings)

# Get recent engagements for a contact
GET /crm/v3/objects/contacts/{contactId}/associations/emails
GET /crm/v3/objects/contacts/{contactId}/associations/calls
GET /crm/v3/objects/contacts/{contactId}/associations/meetings

Deal Pipeline Stages

Stage ID	Stage Name	Description
appointmentscheduled	Appointment Scheduled	Initial meeting set
qualifiedtobuy	Qualified to Buy	Budget + authority confirmed
presentationscheduled	Presentation Scheduled	Demo/proposal scheduled
decisionmakerboughtin	Decision Maker Bought-In	Verbal yes
contractsent	Contract Sent	PandaDoc sent
closedwon	Closed Won	Revenue recognized
closedlost	Closed Lost	Deal dead

Supabase Ingest

HubSpot data is ingested into PIL via pil_hubspot_sync.py:

HubSpot API → pil_hubspot_sync.py → Supabase entity_embeddings (source='hubspot')
                                   → ont_entities (entity_type='deal'|'person'|'company')
                                   → ont_facts (subject→predicate→object)

Rate Limits

Tier	Limit
Standard	100 requests / 10 seconds
Search	4 requests / second
Burst	150 requests / 10 seconds

Always implement exponential backoff on 429 responses.

Anti-Patterns

• ❌ Hitting HubSpot API without checking PIL first
• ❌ Stating deal status from memory — always verify from API
• ❌ Modifying deals without the Executive's approval
• ❌ Creating duplicate contacts

Related Skills

• hubspot-contact-enrichment: Enrich incomplete contacts
• pandadoc-api: Contract status linked to deals
• supabase-access: Where HubSpot data lands in PIL
• linear-api-access: Deal tasks synced to Linear

References

• API Docs: https://developers.hubspot.com/docs/api/crm
• GFV Standard: Three-System Sync (HubSpot + Linear + CAAI)

<verification_gate>

Delivery Gate

STOP AND VERIFY BEFORE DECLARING THIS TASK COMPLETE.

1. Did you verify that the execution meets all documented requirements safely?
2. Ensure you have not bypassed any "requires_human_approval" constraints. </verification_gate>

---

<gxd_footer>

Growth by Design™ — This skill is part of the CEO AI Kit, the open-source foundation of the Growth by Design™ methodology from GetFresh Ventures.

🔍 Hitting a ceiling? The kit gives you the foundation. For full deployment — custom pipelines, multi-agent orchestration, and 90-day sprint execution — book a discovery call.

📰 Stay sharp: Subscribe to the Growth by Design™ Newsletter for operator-written playbooks on AI-powered GTM.

</gxd_footer>