HubSpot

The HubSpot connector ingests CRM objects (contacts, companies, deals, tickets) into the knowledge graph and exposes tools for agents to read, search, and update records. Handy for sales automations, ticket triage, and cross-system enrichment.

Configure

curl -X POST http://localhost:8080/api/v1/sources \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{
    "name":"hubspot-main",
    "connector":"hubspot",
    "realm":"crm",
    "config":{
      "auth":{"kind":"private_app","token":"pat-na1-…"},
      "objects":["contacts","companies","deals","tickets","owners"]
    }
  }'

Auth:

• private_app — recommended. Create a Private App in HubSpot → Settings → Integrations → Private Apps. Grant scopes:
  • crm.objects.contacts.read + .write
  • crm.objects.companies.read + .write
  • crm.objects.deals.read + .write
  • tickets (read + write)
  • crm.schemas.*.read
• oauth — for third-party apps. Agentcy handles the callback; you set HUBSPOT_CLIENT_ID and HUBSPOT_CLIENT_SECRET.

What it ingests

Graph label	HubSpot object	Typical edges
:HubSpotContact	contacts	WORKS_AT → :HubSpotCompany
:HubSpotCompany	companies	HAS_CONTACT, HAS_DEAL
:HubSpotDeal	deals	FOR_COMPANY, PRIMARY_CONTACT, IN_STAGE → :HubSpotStage
:HubSpotTicket	tickets	FOR_CONTACT, IN_PIPELINE
:HubSpotPipeline	pipelines + stages	—
:HubSpotOwner	users	OWNS

Incremental sync uses HubSpot's lastModifiedDate filter. First sync is full.

Tools (read)

• hubspot.search_contacts(query, filters)
• hubspot.get_contact(id|email)
• hubspot.search_companies
• hubspot.get_company
• hubspot.search_deals
• hubspot.get_deal
• hubspot.list_tickets(status)
• hubspot.get_ticket
• hubspot.list_pipelines

Tools (write, approval-gated)

• hubspot.create_note(object_type, object_id, body)
• hubspot.create_task(assignee, dueAt, subject)
• hubspot.update_deal(id, stage, amount, closeDate)
• hubspot.create_ticket

Webhooks

HubSpot webhooks (ticket created, deal stage changed) are delivered to /api/v1/hooks/<trigger_id> if you configure a webhook trigger. See How-To: Webhooks & Triggers.

Agent flows

• "Summarize open deals > $50k with no activity in 14 days." — hubspot.search_deals with filters; ranks by amount; cross-references last activity.
• "Triage new inbound tickets." — lifecycle trigger on node.created for :HubSpotTicket; agent classifies, assigns, and posts to Slack.

Rate limits

HubSpot's limits depend on your tier. Connector respects 429 Retry-After and applies token-bucket backoff.

Gotchas

• Custom properties. Add them to config.properties.contacts to include them in ingestion; otherwise only default fields are synced.
• Associations require the crm.schemas.* scope. Without it, edges are empty and the graph looks disconnected.
• Owner handoff. Deal updates that change hubspot_owner_id fire lifecycle events — useful for routing agents.

Next

• Concept: Connectors
• Webhooks & Triggers — reactive HubSpot flows.