HubSpot

API

The HubSpot connector is an API connector that imports contacts, companies, deals, and notes from HubSpot CRM. It produces structural claims about relationships and deal status, plus extracts claims from note bodies via text extraction.

How it works

Uses the HubSpot CRM v3 API with Bearer token authentication
Fetches 4 object types: contacts, companies, deals, notes
Deal stage IDs are automatically resolved to human-readable names via pipeline API
Notes are linked to contacts/companies/deals via HubSpot associations
Note bodies are optionally run through text extraction
Rate limiting handled automatically (100 requests / 10 seconds)

Claim patterns

Contacts

Subject	Predicate	Object
`(email, contact)`	`works_at`	`(company, company)`
`(email, contact)`	`has_role`	`(jobtitle, role)`
`(email, contact)`	`has_stage`	`(lifecyclestage, stage)`

Companies

Subject	Predicate	Object
`(name, company)`	`in_industry`	`(industry, industry)`
`(name, company)`	`has_domain`	`(domain, domain)`
`(name, company)`	`has_size`	`(employees, size)`

Deals

Subject	Predicate	Object
`(dealname, deal)`	`has_stage`	`(stage_name, stage)`
`(dealname, deal)`	`has_amount`	`($amount, currency)`
`(dealname, deal)`	`in_pipeline`	`(pipeline, pipeline)`
`(dealname, deal)`	`closes_on`	`(date, date)`

Notes

Subject	Predicate	Object
`(note:id, note)`	`associated_with`	`(entity, contact/company/deal)`

All structural claims have confidence 1.0. Note body extraction produces additional claims at extraction-mode confidence.

1 Create a HubSpot Private App

Go to Settings → Integrations → Private Apps in your HubSpot account. Create a new private app and grant the following scopes:

crm.objects.contacts.read
crm.objects.companies.read
crm.objects.deals.read
crm.objects.notes.read (beta) — for notes

2 Install the requests package

$ pip install requests

3 Connect

import os
conn = db.connect("hubspot",
    token=os.environ["HUBSPOT_TOKEN"],
)
result = conn.run(db)

Parameter	Required	Default	Description
`token`	Yes	—	HubSpot private app token (`pat-...`)
`objects`	No	`["contacts", "companies", "deals", "notes"]`	Which object types to fetch
`max_items`	No	`500`	Max items per object type
`extraction`	No	`heuristic`	Text extraction mode for note bodies: `heuristic`, `smart`, `llm`, or `none`
`pipeline`	No	All	Filter deals to specific pipeline
`save`	No	`False`	Encrypt and persist token

Basic usage

conn = db.connect("hubspot",
    token=os.environ["HUBSPOT_TOKEN"],
)
result = conn.run(db)
print(f"Ingested {result.claims_ingested} claims")

Contacts and deals only

conn = db.connect("hubspot",
    token=os.environ["HUBSPOT_TOKEN"],
    objects=["contacts", "deals"],
    pipeline="default",
    max_items=1000,
)
result = conn.run(db)

With LLM extraction and save

conn = db.connect("hubspot",
    token=os.environ["HUBSPOT_TOKEN"],
    extraction="llm",
    save=True,
)
result = conn.run(db)

Notes only (sales intelligence)

conn = db.connect("hubspot",
    token=os.environ["HUBSPOT_TOKEN"],
    objects=["notes"],
    extraction="llm",
)
result = conn.run(db)