HubSpot

Connect to HubSpot for CRM automation including contacts, companies, deals, tickets, and engagement activities.

Overview

HubSpot is an all-in-one CRM platform. The integration supports:

Contacts - Individual contact records
Companies - Organization records
Deals - Sales pipeline and deals
Tickets - Customer support tickets
Associations - Relationships between objects
Engagements - Notes, tasks, and activities
Custom Objects - Any CRM object type

Prerequisites

HubSpot account (Free, Starter, Professional, or Enterprise)
Private app with required scopes
API access enabled

Authentication

HubSpot uses OAuth 2.0 for authentication via Nango.

curl "http://localhost:3000/api/v1/connections/hubspot/auth-url" \
  -H "x-api-key: YOUR_API_KEY"

Required Scopes

Scope	Description
`crm.objects.contacts.read/write`	Contact access
`crm.objects.companies.read/write`	Company access
`crm.objects.deals.read/write`	Deal access
`crm.objects.owners.read`	Owner access

Available Actions

Contact Actions

getContact

Get a contact by ID.

{
  "action": "hubspot.getContact",
  "config": {
    "contactId": "12345",
    "properties": ["email", "firstname", "lastname", "phone", "company"]
  }
}

createContact

Create a new contact.

{
  "id": "create-contact",
  "type": "action",
  "action": "hubspot.createContact",
  "config": {
    "email": "{{input.email}}",
    "firstName": "{{input.firstName}}",
    "lastName": "{{input.lastName}}",
    "phone": "{{input.phone}}",
    "company": "{{input.companyName}}",
    "website": "{{input.website}}",
    "jobTitle": "{{input.title}}",
    "lifecycleStage": "lead",
    "leadStatus": "NEW",
    "address": "{{input.address.street}}",
    "city": "{{input.address.city}}",
    "state": "{{input.address.state}}",
    "zip": "{{input.address.zip}}",
    "country": "{{input.address.country}}",
    "customProperties": {
      "source_workflow": "{{workflowId}}"
    }
  }
}

Parameters:

Field	Type	Required	Description
`email`	string	No	Email address
`firstName`	string	No	First name
`lastName`	string	No	Last name
`phone`	string	No	Phone number
`company`	string	No	Company name
`website`	string	No	Website URL
`jobTitle`	string	No	Job title
`lifecycleStage`	string	No	Lifecycle stage
`leadStatus`	string	No	Lead status
`customProperties`	object	No	Custom property values

updateContact

Update an existing contact.

{
  "action": "hubspot.updateContact",
  "config": {
    "contactId": "{{input.contactId}}",
    "lifecycleStage": "customer",
    "customProperties": {
      "last_workflow_run": "{{now}}"
    }
  }
}

deleteContact

Delete a contact.

{
  "action": "hubspot.deleteContact",
  "config": {
    "contactId": "{{input.contactId}}"
  }
}

searchContacts

Search contacts with filters.

{
  "action": "hubspot.searchContacts",
  "config": {
    "filterGroups": [
      {
        "filters": [
          {
            "propertyName": "lifecyclestage",
            "operator": "EQ",
            "value": "lead"
          },
          {
            "propertyName": "createdate",
            "operator": "GTE",
            "value": "{{input.startDate}}"
          }
        ]
      }
    ],
    "sorts": [
      { "propertyName": "createdate", "direction": "DESCENDING" }
    ],
    "properties": ["email", "firstname", "lastname", "company"],
    "limit": 100,
    "after": "{{steps.previous.output.paging.next.after}}"
  }
}

Company Actions

getCompany

Get a company by ID.

{
  "action": "hubspot.getCompany",
  "config": {
    "companyId": "12345",
    "properties": ["name", "domain", "industry", "numberofemployees"]
  }
}

createCompany

Create a new company.

{
  "id": "create-company",
  "type": "action",
  "action": "hubspot.createCompany",
  "config": {
    "name": "{{input.companyName}}",
    "domain": "{{input.domain}}",
    "description": "{{input.description}}",
    "industry": "{{input.industry}}",
    "phone": "{{input.phone}}",
    "website": "{{input.website}}",
    "numberOfEmployees": "{{input.employees}}",
    "annualRevenue": "{{input.revenue}}",
    "lifecycleStage": "lead",
    "type": "{{input.companyType}}"
  }
}

updateCompany / deleteCompany

{
  "action": "hubspot.updateCompany",
  "config": {
    "companyId": "{{input.companyId}}",
    "industry": "Technology",
    "lifecycleStage": "customer"
  }
}

searchCompanies

{
  "action": "hubspot.searchCompanies",
  "config": {
    "filterGroups": [
      {
        "filters": [
          {
            "propertyName": "industry",
            "operator": "EQ",
            "value": "TECHNOLOGY"
          }
        ]
      }
    ],
    "properties": ["name", "domain", "industry"],
    "limit": 50
  }
}

Deal Actions

getDeal

Get a deal by ID.

{
  "action": "hubspot.getDeal",
  "config": {
    "dealId": "12345",
    "properties": ["dealname", "dealstage", "amount", "closedate"]
  }
}

createDeal

Create a new deal.

{
  "id": "create-deal",
  "type": "action",
  "action": "hubspot.createDeal",
  "config": {
    "dealName": "{{input.dealName}}",
    "dealStage": "appointmentscheduled",
    "pipeline": "default",
    "amount": "{{input.dealValue}}",
    "closeDate": "{{input.expectedCloseDate}}",
    "dealType": "newbusiness",
    "description": "{{input.notes}}",
    "priority": "high",
    "associations": [
      {
        "to": { "id": "{{input.contactId}}" },
        "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 3 }]
      }
    ]
  }
}

Parameters:

Field	Type	Required	Description
`dealName`	string	Yes	Deal name
`dealStage`	string	Yes	Pipeline stage ID
`pipeline`	string	No	Pipeline ID (default: default)
`amount`	number	No	Deal value
`closeDate`	string	No	Expected close date
`dealType`	string	No	Deal type
`description`	string	No	Description
`priority`	string	No	Priority level
`associations`	array	No	Associated records

updateDeal / deleteDeal

{
  "action": "hubspot.updateDeal",
  "config": {
    "dealId": "{{input.dealId}}",
    "dealStage": "closedwon",
    "amount": "{{input.finalAmount}}"
  }
}

searchDeals

{
  "action": "hubspot.searchDeals",
  "config": {
    "filterGroups": [
      {
        "filters": [
          {
            "propertyName": "dealstage",
            "operator": "IN",
            "values": ["presentationscheduled", "decisionmakerboughtin"]
          }
        ]
      }
    ],
    "properties": ["dealname", "amount", "closedate"],
    "limit": 50
  }
}

Ticket Actions

getTicket

Get a ticket by ID.

{
  "action": "hubspot.getTicket",
  "config": {
    "ticketId": "12345",
    "properties": ["subject", "content", "hs_pipeline_stage"]
  }
}

createTicket

Create a support ticket.

{
  "id": "create-ticket",
  "type": "action",
  "action": "hubspot.createTicket",
  "config": {
    "subject": "{{input.subject}}",
    "content": "{{input.description}}",
    "pipeline": "default",
    "pipelineStage": "1",
    "priority": "HIGH",
    "category": "{{input.category}}",
    "associations": [
      {
        "to": { "id": "{{input.contactId}}" },
        "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 16 }]
      }
    ]
  }
}

updateTicket / deleteTicket

{
  "action": "hubspot.updateTicket",
  "config": {
    "ticketId": "{{input.ticketId}}",
    "pipelineStage": "4"
  }
}

Association Actions

createAssociation

Create a relationship between objects.

{
  "action": "hubspot.createAssociation",
  "config": {
    "fromObjectType": "contacts",
    "fromObjectId": "{{input.contactId}}",
    "toObjectType": "companies",
    "toObjectId": "{{input.companyId}}",
    "associationType": "contact_to_company"
  }
}

getAssociations

Get associations for an object.

{
  "action": "hubspot.getAssociations",
  "config": {
    "objectType": "contacts",
    "objectId": "{{input.contactId}}",
    "toObjectType": "deals"
  }
}

deleteAssociation

{
  "action": "hubspot.deleteAssociation",
  "config": {
    "fromObjectType": "contacts",
    "fromObjectId": "{{input.contactId}}",
    "toObjectType": "companies",
    "toObjectId": "{{input.companyId}}",
    "associationType": "contact_to_company"
  }
}

Engagement Actions

createNote

Create a note on a record.

{
  "action": "hubspot.createNote",
  "config": {
    "body": "{{input.noteContent}}",
    "ownerId": "{{input.ownerId}}",
    "associations": [
      {
        "to": { "id": "{{input.contactId}}" },
        "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 202 }]
      }
    ]
  }
}

createTask

Create a task.

{
  "action": "hubspot.createTask",
  "config": {
    "subject": "Follow up call",
    "body": "{{input.taskDescription}}",
    "status": "NOT_STARTED",
    "priority": "HIGH",
    "taskType": "CALL",
    "ownerId": "{{input.ownerId}}",
    "reminderDate": "{{input.dueDate}}",
    "associations": [
      {
        "to": { "id": "{{input.contactId}}" },
        "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 204 }]
      }
    ]
  }
}

updateTask

{
  "action": "hubspot.updateTask",
  "config": {
    "taskId": "{{input.taskId}}",
    "status": "COMPLETED"
  }
}

Owner Actions

getOwner

Get owner details.

{
  "action": "hubspot.getOwner",
  "config": {
    "ownerId": "12345"
  }
}

listOwners

List all owners.

{
  "action": "hubspot.listOwners",
  "config": {
    "email": "{{input.email}}",
    "limit": 100
  }
}

Generic Object Actions

Work with any HubSpot CRM object.

getObject / createObject / updateObject / deleteObject

{
  "action": "hubspot.getObject",
  "config": {
    "objectType": "products",
    "objectId": "12345",
    "properties": ["name", "price"]
  }
}

searchObjects

{
  "action": "hubspot.searchObjects",
  "config": {
    "objectType": "products",
    "filterGroups": [
      {
        "filters": [
          { "propertyName": "price", "operator": "GTE", "value": "100" }
        ]
      }
    ],
    "properties": ["name", "price", "description"],
    "limit": 50
  }
}

Search Operators

Operator	Description
`EQ`	Equal to
`NEQ`	Not equal to
`LT`	Less than
`LTE`	Less than or equal
`GT`	Greater than
`GTE`	Greater than or equal
`BETWEEN`	Between two values
`IN`	In list of values
`NOT_IN`	Not in list
`HAS_PROPERTY`	Property exists
`NOT_HAS_PROPERTY`	Property doesn't exist
`CONTAINS_TOKEN`	Contains text

Webhook Triggers

HubSpot webhooks trigger workflows on CRM changes.

{
  "trigger": {
    "type": "webhook",
    "provider": "hubspot",
    "events": ["contact.creation", "deal.propertyChange"]
  }
}

Event Types:

contact.creation, contact.deletion, contact.propertyChange
company.creation, company.deletion, company.propertyChange
deal.creation, deal.deletion, deal.propertyChange
quote.creation, quote.propertyChange

Triggering on published quotes: quote.propertyChange fires on every hs_status transition (DRAFT, PENDING_APPROVAL, APPROVED, REJECTED, ...). For automations that must only run when a quote is published — especially billing flows that create invoices or subscriptions — narrow the trigger to the property and its new value. Set propertyName to hs_status so the trigger only reacts to status changes, and add a filter whose keys are dot-notation paths into the normalized event. The new status value lives at data.propertyValue:

{
  "trigger": {
    "type": "hubspot_event",
    "eventKind": "quote.propertyChange",
    "propertyName": "hs_status",
    "filter": { "data.propertyValue": "APPROVED" }
  }
}

Filter keys are paths into the normalized event, not raw HubSpot property names — data.propertyName holds which property changed and data.propertyValue holds its new value. The API also accepts the synthetic quote.published event kind, which matches hs_status transitions to APPROVED, APPROVAL_NOT_NEEDED, or PUBLISHED without a manual filter. It is not yet selectable in the Studio event dropdown; use it when authoring workflow JSON directly.

Example Workflow

Lead to deal workflow:

{
  "name": "Convert Lead to Deal",
  "trigger": {
    "type": "webhook",
    "provider": "hubspot",
    "events": ["contact.propertyChange"]
  },
  "steps": [
    {
      "id": "check-lifecycle",
      "type": "condition",
      "config": {
        "conditions": {
          "left": "{{input[0].propertyName}}",
          "operator": "eq",
          "right": "lifecyclestage"
        },
        "then": ["check-stage"],
        "else": []
      }
    },
    {
      "id": "check-stage",
      "type": "condition",
      "config": {
        "conditions": {
          "left": "{{input[0].propertyValue}}",
          "operator": "eq",
          "right": "salesqualifiedlead"
        },
        "then": ["get-contact"],
        "else": []
      }
    },
    {
      "id": "get-contact",
      "type": "action",
      "action": "hubspot.getContact",
      "config": {
        "contactId": "{{input[0].objectId}}",
        "properties": ["email", "firstname", "lastname", "company"]
      }
    },
    {
      "id": "create-deal",
      "type": "action",
      "action": "hubspot.createDeal",
      "config": {
        "dealName": "{{steps.get-contact.output.properties.company}} - New Opportunity",
        "dealStage": "appointmentscheduled",
        "associations": [
          {
            "to": { "id": "{{input[0].objectId}}" },
            "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 3 }]
          }
        ]
      }
    },
    {
      "id": "create-task",
      "type": "action",
      "action": "hubspot.createTask",
      "config": {
        "subject": "Initial discovery call with {{steps.get-contact.output.properties.firstname}}",
        "status": "NOT_STARTED",
        "priority": "HIGH",
        "associations": [
          {
            "to": { "id": "{{steps.create-deal.output.id}}" },
            "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 216 }]
          }
        ]
      }
    }
  ]
}

Rate Limits

Limit	Value
API calls per day	250,000 (Professional)
API calls per second	150
Batch operations	100 records per batch
Search results	10,000 max

Troubleshooting

Common Errors

Error	Cause	Solution
`PROPERTY_DOESNT_EXIST`	Invalid property name	Check property API name
`CONFLICT`	Duplicate record	Use search to find existing
`RATE_LIMIT`	Too many requests	Implement backoff
`OBJECT_NOT_FOUND`	Invalid object ID	Verify ID exists

HubSpot

On this page