HubSpot Agent

The hubspot agent connects to the HubSpot CRM API v3 using a private app access token. It fetches contacts, deals, and companies by ID, searches contacts by query, and creates engagement notes. Source data is written as JSON to the workspace.

Use this agent to bring CRM context into your pipelines — pull customer data for personalized workflows, search for accounts before outreach, or log engagement notes after automated interactions.

Sample Phase

- name: fetch-contact
  agent: hubspot
  action: get_contact
  sources:
      - name: contact.json
        ref: "[email protected]"

Phase Configuration

The hubspot agent uses phase:standard capability. Every phase declaration requires an action field.

Actions

Action	Direction	Description
`get_contact`	Source	Fetch a contact by ID or email
`get_deal`	Source	Fetch a deal by ID
`get_company`	Source	Fetch a company by ID
`search`	Source	Search contacts by query string
`add_note`	Target	Create an engagement note on a CRM object

Phase YAML Fields

Field	Type	Required	Description
`name`	`string`	Yes	Unique phase name within the workflow
`type`	`string`	No	Defaults to `"standard"`
`agent`	`string`	Yes	Must be `"hubspot"`
`depends_on`	`string[]`	No	Upstream phases that must complete before this phase runs
`action`	`string`	Yes	One of: `get_contact`, `get_deal`, `get_company`, `search`, `add_note`
`sources`	`SourceEntry[]`	For fetch actions	Entries to fetch from HubSpot
`target_entries`	`TargetEntry[]`	For write actions	Entries to deliver to HubSpot

Source Entry Fields

Field	Type	Required	Description
`name`	`string`	Yes	Output filename written to `.cliq/files/{phase}/`
`ref`	`string`	Yes	Object ID, email address (`get_contact`), or search query string (`search`)

Target Entry Fields

Field	Type	Required	Description
`name`	`string`	Yes	Identifier for the operation
`ref`	`string`	Yes	CRM object ID to attach the note to
`file`	`string`	Yes	Workspace file containing the note content

Settings

Key	Required	Default	Description
`agents.hubspot.access_token`	Yes	—	HubSpot private app access token

Output

Handoff Structure

Source operation — get_contact:

{
    "data": {
        "action": "get_contact",
        "sources": {
            "contact.json": {
                "ref": "12345",
                "object_type": "contact",
                "object_id": "12345",
                "properties": ["firstname", "lastname", "email", "company"]
            }
        },
        "targets": {}
    },
    "text": "## HubSpot Results\n\n✓ Fetched contact.json — contact #12345"
}

Source operation — search:

{
    "data": {
        "action": "search",
        "sources": {
            "results.json": {
                "ref": "acme",
                "object_type": "contact",
                "count": 3
            }
        },
        "targets": {}
    },
    "text": "## HubSpot Results\n\n✓ Searched results.json — 3 contacts matched"
}

Target operation — add_note:

{
    "data": {
        "action": "add_note",
        "sources": {},
        "targets": {
            "note": {
                "ref": "12345",
                "object_type": "contact",
                "object_id": "12345",
                "action_taken": "note_created"
            }
        }
    },
    "text": "## HubSpot Results\n\n✓ Added note to contact #12345"
}

Field Reference

Field	Location	Description
`ref`	`data.sources.`, `data.targets.`	Original ref value (object ID, email, or search query)
`object_type`	`data.sources.`, `data.targets.`	CRM object type (`contact`, `deal`, `company`)
`object_id`	`data.sources.`, `data.targets.`	HubSpot object ID
`properties`	`data.sources.*`	List of property names included in the response
`count`	`data.sources.*`	Number of search results (present on `search`)
`action_taken`	`data.targets.*`	Action performed (e.g., `note_created`)

Files Written

Source responses are saved to .cliq/files/{phase}/{source.name} as JSON. Contact/deal/company data includes all default HubSpot properties.

Downstream Access

Reference CRM data in downstream phases:

commands:
    - name: report
      run: 'echo "Found $(handoff.search-contacts.sources.results.json.count) contacts"'

Examples

Example: Pull customer context for support

Fetch a contact and their deal, then hand off to an AI agent with full customer context.

phases:
    - name: fetch-customer
      agent: hubspot
      action: get_contact
      sources:
          - name: contact.json
            ref: "[email protected]"

    - name: fetch-deal
      agent: hubspot
      action: get_deal
      sources:
          - name: deal.json
            ref: "987654"

    - name: draft-response
      agent: cursor
      role: account-manager
      depends_on: [fetch-customer, fetch-deal]

Example: Search and enrich leads

Search for contacts matching a query, then process the results with an analyst agent.

phases:
    - name: find-leads
      agent: hubspot
      action: search
      sources:
          - name: leads.json
            ref: "company:acme lifecycle_stage:lead"

    - name: enrich
      agent: cursor
      role: sales-analyst
      depends_on: [find-leads]

Example: Log an engagement note after outreach

After an automated outreach phase completes, log a note on the contact record.

phases:
    - name: outreach
      agent: cursor
      role: outreach-specialist

    - name: log-note
      agent: hubspot
      action: add_note
      depends_on: [outreach]
      target_entries:
          - name: note
            ref: "12345"
            file: engagement-note.txt

Example: Fetch company data for a report

Pull company details and feed them into a reporting pipeline.

phases:
    - name: fetch-company
      agent: hubspot
      action: get_company
      sources:
          - name: company.json
            ref: "555111"

    - name: generate-report
      agent: cursor
      role: analyst
      depends_on: [fetch-company]

Setup

In HubSpot, go to Settings → Integrations → Private Apps
Click Create a private app
Name it (e.g., cliq-integration) and select the required scopes:
- crm.objects.contacts.read
- crm.objects.deals.read
- crm.objects.companies.read
- crm.objects.contacts.write (for add_note)
Create the app and copy the access token

echo $HUBSPOT_TOKEN | cliq settings agents.hubspot.access_token --stdin --global
cliq doctor agent hubspot