HubSpot Connector

The HubSpot connector ingests CRM objects and engagement activities from HubSpot into CortexDB as typed episodes. Contacts, Companies, Deals, Tickets, Notes, Emails, Calls, and Tasks are all captured.

Setup

1. Create a HubSpot Private App

1. In HubSpot, go to Settings > Integrations > Private Apps
2. Create a new app with the following scopes:
   • crm.objects.contacts.read
   • crm.objects.companies.read
   • crm.objects.deals.read
   • tickets
   • e-commerce (for engagements)
3. Copy the generated Access Token

2. Configure the Connector

export CORTEX_HUBSPOT_ACCESS_TOKEN=pat-na1-your-access-token
export CORTEX_HUBSPOT_TENANT_ID=my-app
export CORTEX_HUBSPOT_NAMESPACE=hubspot

3. Start the Connector

cortexdb-connector hubspot \
  --access-token pat-na1-your-access-token \
  --tenant-id my-app

Or with Docker:

docker run -d \
  --name cortex-hubspot \
  -e CORTEX_HUBSPOT_ACCESS_TOKEN=pat-na1-your-access-token \
  -e CORTEX_HUBSPOT_TENANT_ID=my-app \
  cortexdb/connector-hubspot:latest

What Gets Ingested

| HubSpot Object | Episode Type | Content | |---|---|---| | Contact | document | Name, email, company, lifecycle stage | | Company | document | Name, industry, domain, revenue | | Deal | document | Deal name, stage, amount, close date | | Ticket | issue | Subject, content, priority, pipeline stage | | Note | message | Note body text | | Email | message | Email subject and body | | Call | message | Call title, duration, body | | Task | issue | Task subject, status, body |

Episode Metadata

{
  "type": "document",
  "content": "Deal [closedwon]: Enterprise Annual License ($120,000.00)",
  "source": "hubspot",
  "timestamp": "2026-03-16T10:15:00Z",
  "metadata": {
    "hubspot_object": "deals",
    "hubspot_id": "12345678",
    "deal_stage": "closedwon",
    "pipeline": "default"
  },
  "entities": [
    { "type": "deal", "id": "12345678", "name": "Enterprise Annual License" },
    { "type": "user", "id": "98765432", "name": "98765432" },
    { "type": "pipeline", "id": "default", "name": "default" }
  ]
}

Configuration

| Variable | Default | Description | |---|---|---| | CORTEX_HUBSPOT_ACCESS_TOKEN | Required | HubSpot private app access token | | CORTEX_HUBSPOT_OBJECTS | contacts,companies,deals,tickets,notes,emails,calls,tasks | Comma-separated object types | | CORTEX_HUBSPOT_TENANT_ID | Required | Target tenant | | CORTEX_HUBSPOT_NAMESPACE | hubspot | Target namespace | | CORTEX_HUBSPOT_BACKFILL_DAYS | 90 | Days of history to backfill | | CORTEX_HUBSPOT_POLL_INTERVAL_SEC | 60 | Polling interval |

Backfill

On first run, the connector backfills records modified within the last CORTEX_HUBSPOT_BACKFILL_DAYS days (default 90). CRM objects use the search API with lastmodifieddate filtering. Engagement objects use the basic list API with client-side date filtering. All endpoints support cursor-based pagination.