HubSpot Integration

Connect Agents to HubSpot to automate CRM tasks, create follow-ups, and keep your sales data in sync.

Overview

The HubSpot integration enables workflows to:

• Create tasks associated with deals, contacts, or companies
• Update deals with new information from meetings
• Log meetings automatically to HubSpot
• Create notes on CRM records

Prerequisites

Before connecting HubSpot:

1. HubSpot account with appropriate plan (Professional or Enterprise recommended)
2. Admin access or permission to install integrations
3. CRM access to objects you want to automate (Deals, Contacts, Tasks)

Connecting HubSpot

Step 1: Navigate to Integrations

1. Go to Workspace Settings
2. Select Integrations
3. Find HubSpot in the list

Step 2: Authorize Connection

1. Click Connect
2. Log in to your HubSpot account (if not already logged in)
3. Review the requested permissions
4. Click Grant access

Step 3: Verify Connection

After authorization:

• Connection status shows "Connected"
• Your HubSpot portal ID is displayed
• You can test the connection

Required Permissions

The HubSpot integration requests these scopes:

Available Actions

Create HubSpot Task

Create a task associated with a HubSpot object.

Configuration:

Example:

[AI: Extract action items] ──▶ [Create HubSpot Task]

With configuration:

• object_type: deals
• object_id: {{ json.dealId }}
• subject: Follow up: {{ json.actionItem }}
• body: From meeting on {{ trigger.firedAt | date: "%B %d" }}
• priority: HIGH

Update CRM (Opportunity/Deal)

Update deal fields after meetings.

Configuration:

Common updatable fields:

• dealname - Deal name
• amount - Deal value
• dealstage - Pipeline stage
• closedate - Expected close date
• hs_next_step - Next step text
• Custom fields - Any custom deal properties

Working with HubSpot Objects

Finding Object IDs

HubSpot object IDs are needed to associate tasks or update records:

From meeting context:

{{ json.meeting.externalServiceObjects | where: "type", "DEAL" | first | map: "externalId" }}

From Deal Room:

{{ json.dealRoom.hubspotDealId }}

Object Types

Pipeline and Stages

When updating deal stages, use the stage ID (not name):

[CRM Update Opportunity]
field_values:
  dealstage: "closedwon"  // Stage ID from HubSpot

To find stage IDs:

1. Go to HubSpot → Settings → Objects → Deals → Pipelines
2. Select your pipeline
3. Each stage has an internal ID

Field Mappings

Standard Fields

Custom Fields

Access custom fields by their internal name (not label):

1. Go to HubSpot → Settings → Properties
2. Find your custom property
3. Copy the Internal name
4. Use in field_values

Example:

{
  "my_custom_field_internal_name": "value"
}

Task Statuses and Priorities

Task Status Values

Task Priority Values

Example Workflows

Post-Meeting Task Creation

[Event: MEETING_ENDED]
        │
        ▼
[Load Meeting]
        │
        ▼
[AI: Extract action items]
        │
        ▼
[Select Many: action items]
        │
        ▼
[Create HubSpot Task]

AI Prompt:

Extract action items from this meeting. Return as a list of strings.

Meeting: {{ json.meeting.title }}
Summary: {{ json.callRecording.transcriptSummary }}

Task Configuration:

• subject: {{ json.item }}
• body: Action from meeting: {{ trigger.meetingPlanId }}
• status: NOT_STARTED
• priority: MEDIUM

Deal Stage Update

[Event: MEETING_ENDED]
        │
        ▼
[Load Meeting]
        │
        ▼
[If: has deal associated?]
        │
        ├── Yes ──▶ [AI: Analyze deal progress]
        │                    │
        │                    ▼
        │           [CRM Update Opportunity]
        │
        └── No ───▶ [Sink]

Best Practices

1. Use Association Types Correctly

Always specify the correct object_type when creating tasks:

• Tasks for deals → object_type: deals
• Tasks for contacts → object_type: contacts
• Tasks for companies → object_type: companies

2. Validate Stage IDs

Before updating deal stages, verify the stage ID exists in the target pipeline. Invalid stage IDs will cause errors.

3. Handle Missing Objects

Check that HubSpot objects exist before trying to update:

[If: has HubSpot deal?]
    ├── Yes ──▶ [Update Deal]
    └── No ───▶ [Log: No deal found] ──▶ [Sink]

4. Date Formatting

HubSpot expects dates in ISO 8601 format:

{{ json.date | date: "%Y-%m-%dT%H:%M:%SZ" }}

For task due dates:

{{ "now" | date: "%Y-%m-%dT17:00:00Z" }}  // Today at 5 PM UTC

Troubleshooting

Common Errors

Token Refresh Issues

If workflows consistently fail with auth errors:

1. Disconnect the HubSpot integration
2. Wait 30 seconds
3. Reconnect and re-authorize
4. Test with a simple workflow

Rate Limits

HubSpot has API rate limits (varies by plan). If you hit limits:

• Add delays between operations
• Batch similar operations
• Consider spreading workflows across time

Security Considerations

Data Access

The integration only accesses data the connected user has permission to see in HubSpot. Field-level security is respected.

Token Storage

• OAuth tokens are encrypted at rest
• Tokens are automatically refreshed before expiration
• Refresh tokens are securely stored

Audit Trail

All HubSpot operations are logged and can be traced back to the workflow execution.

Related

• Create HubSpot Task Node
• CRM Update Node
• Salesforce Integration