Skip to main content

​
HubSpot Setup Guide

Get your HubSpot account connected to Agent.AI and ready to build workflows. Time to complete: 10 minutes

​
What You’ll Need

Before you start:
  • Active HubSpot account (any tier: Free, Starter, Professional, Enterprise)
  • Admin access (or permissions to authorize integrations)
  • The workflows/objects you want to automate

​
Step 1: Connect HubSpot to Agent.AI

​
Connect Your Account

  1. In Agent.AI, go to Settings → Integrations
  2. Find HubSpot in the list
  3. Click Connect
  4. You’ll be redirected to HubSpot
  5. Log in to HubSpot (if not already logged in)
  6. Click Grant access or Authorize
  7. You’ll be redirected back to Agent.AI
  8. Connection complete!
You’ll see: “HubSpot Connected” with your account name

​
Authorize Permissions

When connecting, HubSpot asks which permissions (scopes) to grant. Recommended permissions for most workflows:
  • ✅ Read contacts
  • ✅ Write contacts
  • ✅ Read companies
  • ✅ Write companies
  • ✅ Read deals
  • ✅ Write deals
  • ✅ Read engagements
  • ✅ Write timeline events
Why these permissions:
  • Read = View data from HubSpot
  • Write = Create and update records in HubSpot
  • Engagements = Access call/email/meeting history
  • Timeline events = Log custom events to HubSpot
Can I add more later? Yes! If you need additional permissions, just reconnect HubSpot and select more scopes.

​
Step 2: Verify Connection

​
Test the Connection

Quick test:
  1. Create a new workflow in Agent.AI
  2. Add a Search HubSpot (V2) action
  3. Select object type (e.g., “Contacts”)
  4. Click Test or Run
  5. If you see results → Connection works!
If you see an error:
  • Check connection in Settings → Integrations
  • Verify you granted necessary permissions
  • Try reconnecting HubSpot

​
Step 3: Understand Your Setup

​
Which HubSpot Account is Used?

Regular workflows:
  • Uses your HubSpot credentials (the person running the workflow)
  • Your permissions = workflow’s permissions
Lead magnet workflows:
  • Uses builder’s HubSpot credentials (workflow creator)
  • For public workflows on your website
This happens automatically - you don’t configure it.

​
What Can You Access?

You can access:
  • Any HubSpot objects you have permission to view
  • Any properties you have permission to edit
  • Any data in your connected HubSpot account
You cannot access:
  • Objects you don’t have permission for
  • Properties restricted by your HubSpot role
  • Data from other HubSpot accounts (unless separately connected)

​
Common Setup Scenarios

​
Scenario 1: Basic Contact Management

Goal: Search, update, and enrich contacts Permissions needed:
  • Read contacts ✅
  • Write contacts ✅
Test workflow:
  1. Search HubSpot (V2) - Find contacts
  2. Update HubSpot Object (V2) - Update a property
  3. Run and verify update in HubSpot

​
Scenario 2: Deal Pipeline Automation

Goal: Analyze deals and update stages Permissions needed:
  • Read contacts ✅
  • Read deals ✅
  • Write deals ✅
  • Read engagements ✅ (for deal history)
  • Write timeline events ✅ (for logging insights)
Test workflow:
  1. Search HubSpot (V2) - Find deals in a stage
  2. Get Timeline Events (V2) - Get deal activity
  3. Update HubSpot Object (V2) - Update deal
  4. Create Timeline Event (V2) - Log analysis

​
Scenario 3: Webhook-Triggered Enrichment

Goal: Enrich contacts when created in HubSpot Setup steps:
  1. Connect HubSpot to Agent.AI (this guide)
  2. Create Agent.AI workflow with webhook trigger
  3. Copy webhook URL
  4. In HubSpot: Create workflow with “Send webhook” action
  5. Paste webhook URL and configure payload
Permissions needed:
  • Read contacts ✅
  • Write contacts ✅
  • Write timeline events ✅ (optional, for logging)
See: Webhook Triggers Guide for detailed setup

​
Required Properties

​
Standard Properties Always Available

Contacts:
  • firstname, lastname, email, phone
  • company, jobtitle, industry
  • lifecyclestage, hs_lead_status
  • createdate, lastmodifieddate
  • hs_object_id (HubSpot ID)
Deals:
  • dealname, amount, dealstage
  • closedate, pipeline, deal_type
  • createdate, hs_lastmodifieddate
  • hs_object_id (HubSpot ID)
Companies:
  • name, domain, industry
  • city, state, country
  • numberofemployees, annualrevenue
  • createdate, hs_lastmodifieddate
  • hs_object_id (HubSpot ID)

​
Custom Properties

Can I use custom properties? Yes! Any custom properties you’ve created in HubSpot are available. To find them:
  1. In Search/Lookup/Update actions, click ”+ Add Property”
  2. Search for your custom property name
  3. Select it
Custom property names:
  • Usually lowercase with underscores
  • Match what you see in HubSpot settings
  • Example: lead_score, company_tier, onboarding_status

​
Troubleshooting Setup

​
Can’t Connect HubSpot

Error when trying to connect Possible causes:
  1. Not logged into HubSpot
  2. Don’t have permission to authorize integrations
  3. Browser blocking popup
How to fix:
  1. Log into HubSpot first
  2. Ask HubSpot admin to authorize
  3. Allow popups for Agent.AI
  4. Try incognito/private browsing

​
Permission Denied Errors

Workflow fails with “permission denied” Possible causes:
  1. Missing required scope/permission
  2. HubSpot user role doesn’t allow access
  3. Object type not available on your HubSpot tier
How to fix:
  1. Reconnect HubSpot and grant more permissions
  2. Check your HubSpot user role permissions
  3. Verify feature available on your HubSpot plan

​
Connection Expired

Workflows suddenly stop working Possible causes:
  1. HubSpot token expired (shouldn’t happen - auto-refreshes)
  2. Changed HubSpot password
  3. Disconnected integration in HubSpot
How to fix:
  1. Go to Settings → Integrations
  2. Disconnect HubSpot
  3. Reconnect HubSpot
  4. Test workflows again

​
Can’t Find Properties

Property doesn’t appear in picker Possible causes:
  1. Property doesn’t exist in HubSpot
  2. Using wrong object type
  3. Custom property not synced yet
How to fix:
  1. Verify property exists in HubSpot settings
  2. Check object type matches (contact vs. company vs. deal)
  3. Wait a few minutes and refresh
  4. Use exact internal property name

​
Tips & Best Practices

✅ Do:
  • Grant all permissions you think you’ll need
  • Test connection with a simple workflow first
  • Use test records/contacts for initial testing
  • Keep HubSpot and Agent.AI in separate browser tabs
  • Document which workflows need which permissions
❌ Don’t:
  • Grant only minimal permissions (reconnecting is tedious)
  • Test with real customer data initially
  • Assume all properties are available (check first)
  • Delete the HubSpot connection while workflows are running
Security:
  • Only connect your own HubSpot account
  • Review permissions before authorizing
  • Disconnect integration if no longer needed
  • Use HubSpot user roles to limit access

​
Next Steps

Now that HubSpot is connected:
  1. Build your first workflow:
  2. Try example workflows:
  3. Set up advanced features:
Foundation: Guides: Actions:
Last Updated: 2025-10-01