HubSpot integration

Overview

The HubSpot tool provides full CRM operations for managing contacts, companies, deals, tickets, engagements (emails, tasks, meetings, calls), and contact lists. It supports create, read, update, delete, search, and bulk list operations across all HubSpot CRM object types. Uses OAuth2 / API key / App Token authentication against the HubSpot API (api.hubapi.com). Supports pagination for large result sets with returnAll/limit parameters. Contact search uses CRM v3 filter groups with property-based filtering.

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires HubSpot API credentials. See the Credentials Guide for setup instructions.

Resources

Resource	Value
Company	company
Contact	contact
Contact List	contactList
Deal	deal
Engagement	engagement
Ticket	ticket

Operations

Which operations are available depends on the selected resource — see the parameter subsections below.

Operation	Value	Description
Create or Update	upsert	Create a contact, or update the existing contact with the same email address.
Delete	delete	Delete a record by its ID.
Get	get	Retrieve a single record by its ID.
Get Many	getAll	List records, one output item per record.
Get Recently Created/Updated	getRecentlyCreatedUpdated	List records that were created or modified recently.
Search	search	Find records using property filter groups.
Create	create	Create a new record.
Search by Domain	searchByDomain	Find companies by their website domain.
Update	update	Update an existing record by its ID.
Add	add	Add a contact to a contact list.
Remove	remove	Remove a contact from a contact list.

Parameters

Company: Create

Parameter	Type	Required	Default	Description
Name	string	Yes	—	The name of the company.
Company Properties (additionalFields)	collection	No	{}	—
— About Us	string	No	—	—
— Annual Revenue	number	No	0	—
— City	string	No	—	—
— Company Domain Name	string	No	—	—
— Company Owner ID	string	No	—	Owner ID.
— Country/Region	string	No	—	—
— Custom Properties (customPropertiesUi)	fixedCollection	No	{}	—
— — Property Name	string	No	—	—
— — Value	string	No	—	—
— Description	string	No	—	—
— Industry	string	No	—	Industry value.
— Is Public	boolean	No	false	—
— Lead Status	string	No	—	—
— Lifecycle Status	string	No	—	—
— Number of Employees	number	No	0	—
— Phone Number	string	No	—	—
— Postal Code	string	No	—	—
— State/Region	string	No	—	—
— Street Address	string	No	—	—
— Street Address 2	string	No	—	—
— Type	string	No	—	—
— Website URL	string	No	—	—
— Year Founded	string	No	—	—

Company: Delete

Parameter	Type	Required	Default	Description
Company ID	string	Yes	—	The HubSpot company ID.

Company: Get

Parameter	Type	Required	Default	Description
Company ID	string	Yes	—	The HubSpot company ID.
Additional Fields	collection	No	{}	—
— Include Merge Audits	boolean	No	false	—

Company: Get Many

Parameter	Type	Required	Default	Description
Options	collection	No	{}	—
— Properties	string	No	—	Comma-separated list of property names to return.
— Property Mode	options	No	value_only	—
				Options: value_only, value_and_history
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)

Company: Get Recently Created/Updated

Parameter	Type	Required	Default	Description
Additional Fields	collection	No	{}	—
— Since	dateTime	No	—	Only return results modified after this date.
— Properties	string	No	—	—
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)

Company: Search by Domain

Parameter	Type	Required	Default	Description
Domain	string	Yes	—	Website domain to search (without protocol, e.g., “example.com”).
Options	collection	No	{}	—
— Properties	string	No	—	Comma-separated list of property names to include.
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)

Company: Update

Parameter	Type	Required	Default	Description
Company ID	string	Yes	—	The HubSpot company ID.
Update Fields	collection	No	{}	—
— Name	string	No	—	—
— About Us	string	No	—	—
— Annual Revenue	number	No	0	—
— City	string	No	—	—
— Company Domain Name	string	No	—	—
— Company Owner ID	string	No	—	—
— Country/Region	string	No	—	—
— Custom Properties (customPropertiesUi)	fixedCollection	No	{}	—
— — Property Name	string	No	—	—
— — Value	string	No	—	—
— Description	string	No	—	—
— Industry	string	No	—	—
— Lead Status	string	No	—	—
— Lifecycle Status	string	No	—	—
— Number of Employees	number	No	0	—
— Phone Number	string	No	—	—
— Postal Code	string	No	—	—
— State/Region	string	No	—	—
— Street Address	string	No	—	—
— Type	string	No	—	—
— Website URL	string	No	—	—
— Year Founded	string	No	—	—

Contact: Create or Update

Parameter	Type	Required	Default	Description
Email	string	Yes	—	Contact email address (used as unique identifier for upsert).
Contact Properties (additionalFields)	collection	No	{}	—
— Annual Revenue	number	No	0	—
— Associated Company ID	string	No	—	Company ID to associate after creation.
— City	string	No	—	—
— Company Name	string	No	—	—
— Contact Owner ID	string	No	—	Owner ID. Find via HubSpot Settings > Users & Teams.
— Country/Region	string	No	—	—
— Custom Properties (customPropertiesUi)	fixedCollection	No	{}	—
— — Property Name	string	No	—	—
— — Value	string	No	—	—
— Description	string	No	—	—
— First Name	string	No	—	—
— Gender	string	No	—	—
— Industry	string	No	—	—
— Job Title	string	No	—	—
— Last Name	string	No	—	—
— Lead Status	string	No	—	Lead status value. Fetch valid values from GET /properties/v2/contacts/properties (hs_lead_status).
— Life Cycle Stage	string	No	—	Lifecycle stage value (e.g., subscriber, lead, opportunity, customer).
— Mobile Phone Number	string	No	—	—
— Number of Employees	string	No	—	—
— Original Source	string	No	—	—
— Phone Number	string	No	—	—
— Postal Code	string	No	—	—
— State/Region	string	No	—	—
— Street Address	string	No	—	—
— Website URL	string	No	—	—
Options	collection	No	{}	—
— Resolve Data	boolean	No	true	Whether to fetch the full contact profile after upsert.

Contact: Delete

Parameter	Type	Required	Default	Description
Contact ID (contactId)	string	Yes	—	The VID of the contact.

Contact: Get

Parameter	Type	Required	Default	Description
Contact ID (contactId)	string	Yes	—	The VID of the contact.
Additional Fields	collection	No	{}	—
— Form Submission Mode	options	No	all	—
				Options: all, none, newest, oldest
— List Memberships	boolean	No	false	—
— Properties	string	No	—	Comma-separated list of property names to return.
— Property Mode	options	No	value_only	—
				Options: value_only, value_and_history

Contact: Get Many

Parameter	Type	Required	Default	Description
Additional Fields	collection	No	{}	—
— Form Submission Mode	options	No	all	—
				Options: all, none, newest, oldest
— List Memberships	boolean	No	false	—
— Properties	string	No	—	Comma-separated list of property names to return.
— Property Mode	options	No	value_only	—
				Options: value_only, value_and_history
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)

Contact: Get Recently Created/Updated

Parameter	Type	Required	Default	Description
Additional Fields	collection	No	{}	—
— Form Submission Mode	options	No	all	—
				Options: all, none, newest, oldest
— List Memberships	boolean	No	false	—
— Properties	string	No	—	Comma-separated list of property names to return.
— Property Mode	options	No	value_only	—
				Options: value_only, value_and_history
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)

Contact: Search

Parameter	Type	Required	Default	Description
Filter Groups (filterGroupsUi)	fixedCollection	No	{}	Filter groups for search (max 3 groups, AND within group, OR across groups).
— Filters	fixedCollection	No	{}	—
— — Property Name	string	No	—	Contact property internal name.
— — Operator	options	No	EQ	—
				Options: EQ (equal), NEQ (not equal), LT (less than), LTE (less than or equal), GT (greater than), GTE (greater than or equal), HAS_PROPERTY, NOT_HAS_PROPERTY, CONTAINS_TOKEN, NOT_CONTAINS_TOKEN
— — Value	string	No	—	—
Additional Fields	collection	No	{}	—
— Sort By	string	No	createdate	—
— Direction	options	No	DESCENDING	—
				Options: ASCENDING, DESCENDING
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)

Contact List: Add

Parameter	Type	Required	Default	Description
List ID	string	Yes	—	The ID of the contact list.
By	options	Yes	email	Whether to identify the contact by ID or email.
				Options: id (Contact ID), email (Email)
Email	string	Yes	—	(shown when By is email)
Contact ID (id)	string	Yes	—	(shown when By is id)

Contact List: Remove

Parameter	Type	Required	Default	Description
List ID	string	Yes	—	The ID of the contact list.
Contact ID (id)	string	Yes	—	—

Deal: Create

Parameter	Type	Required	Default	Description
Deal Stage (stage)	string	Yes	—	Deal stage ID. Find via HubSpot Settings > Deals > Pipelines, or GET /crm-pipelines/v1/pipelines/deals.
Deal Properties (additionalFields)	collection	No	{}	—
— Amount	string	No	—	—
— Associated Company IDs (associatedCompany)	string	No	—	Comma-separated company IDs.
— Associated Contact VIDs (associatedVids)	string	No	—	Comma-separated contact VIDs.
— Close Date	dateTime	No	—	—
— Custom Properties (customPropertiesUi)	fixedCollection	No	{}	—
— — Property Name	string	No	—	—
— — Value	string	No	—	—
— Deal Name	string	No	—	—
— Deal Owner ID	string	No	—	Owner ID.
— Deal Type	string	No	—	Deal type value. Find via GET /properties/v1/deals/properties/named/dealtype.
— Description	string	No	—	—
— Pipeline	string	No	—	Pipeline ID. Find via GET /crm/v3/pipelines/deals.

Deal: Delete

Parameter	Type	Required	Default	Description
Deal ID	string	Yes	—	The HubSpot deal ID.

Deal: Get

Parameter	Type	Required	Default	Description
Deal ID	string	Yes	—	The HubSpot deal ID.
Filters	collection	No	{}	—
— Include Property Versions	boolean	No	false	—
— Properties	string	No	—	Comma-separated list of property names to return.

Deal: Get Many

Parameter	Type	Required	Default	Description
Filters	collection	No	{}	—
— Include Associations	boolean	No	false	—
— Properties	string	No	—	Comma-separated list of property names to return.
— Properties with History	string	No	—	—
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)

Deal: Get Recently Created/Updated

Parameter	Type	Required	Default	Description
Filters	collection	No	{}	—
— Since	dateTime	No	—	—
— Include Property Versions	boolean	No	false	—
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)

Deal: Search

Parameter	Type	Required	Default	Description
Filter Groups (filterGroupsUi)	fixedCollection	No	{}	—
— Filters	fixedCollection	No	{}	—
— — Property Name	string	No	—	—
— — Operator	options	No	EQ	—
				Options: EQ (equal), NEQ (not equal), LT (less than), LTE (less than or equal), GT (greater than), GTE (greater than or equal), HAS_PROPERTY, NOT_HAS_PROPERTY, CONTAINS_TOKEN, NOT_CONTAINS_TOKEN
— — Value	string	No	—	—
Additional Fields	collection	No	{}	—
— Sort By	string	No	createdate	—
— Direction	options	No	DESCENDING	—
				Options: ASCENDING, DESCENDING
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)

Deal: Update

Parameter	Type	Required	Default	Description
Deal ID	string	Yes	—	The HubSpot deal ID.
Update Fields	collection	No	{}	—
— Amount	string	No	—	—
— Close Date	dateTime	No	—	—
— Custom Properties (customPropertiesUi)	fixedCollection	No	{}	—
— — Property Name	string	No	—	—
— — Value	string	No	—	—
— Deal Name	string	No	—	—
— Deal Owner ID	string	No	—	—
— Deal Type	string	No	—	—
— Description	string	No	—	—
— Pipeline	string	No	—	—
— Stage	string	No	—	—

Engagement: Create

Parameter	Type	Required	Default	Description
Type	options	Yes	email	The type of engagement to create.
				Options: call, email, meeting, task
Metadata	collection	No	{}	—
— Body / Notes	string	No	—	—
— Subject	string	No	—	—
— From Email	string	No	—	(shown when Type is email)
— First Name	string	No	—	(shown when Type is email)
— Last Name	string	No	—	(shown when Type is email)
— CC	string	No	—	Comma-separated email addresses. (shown when Type is email)
— BCC	string	No	—	(shown when Type is email)
— HTML	string	No	—	(shown when Type is email)
— Text	string	No	—	(shown when Type is email)
— Status	options	No	NOT_STARTED	(shown when Type is task)
				Options: NOT_STARTED, IN_PROGRESS, WAITING, COMPLETED, DEFERRED
— For Object Type	options	No	CONTACT	(shown when Type is task)
				Options: CONTACT, COMPANY, DEAL, TICKET
— Start Time	dateTime	No	—	(shown when Type is meeting)
— End Time	dateTime	No	—	(shown when Type is meeting)
— Title	string	No	—	(shown when Type is meeting)
— Internal Meeting Notes	string	No	—	(shown when Type is meeting)
— To Number	string	No	—	(shown when Type is call)
— From Number	string	No	—	(shown when Type is call)
— Duration (ms)	number	No	0	(shown when Type is call)
— Recording URL	string	No	—	(shown when Type is call)
Additional Fields	collection	No	{}	—
— Associations	collection	No	{}	—
— — Owner ID	number	No	0	—
— — Company IDs	string	No	—	Comma-separated company IDs.
— — Contact IDs	string	No	—	Comma-separated contact VIDs.
— — Deal IDs	string	No	—	Comma-separated deal IDs.
— — Ticket IDs	string	No	—	Comma-separated ticket IDs.

Engagement: Delete

Parameter	Type	Required	Default	Description
Engagement ID	string	Yes	—	The HubSpot engagement ID.

Engagement: Get

Parameter	Type	Required	Default	Description
Engagement ID	string	Yes	—	The HubSpot engagement ID.

Engagement: Get Many

Parameter	Type	Required	Default	Description
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)

Ticket: Create

Parameter	Type	Required	Default	Description
Pipeline ID	string	Yes	—	Pipeline ID. Find via GET /crm-pipelines/v1/pipelines/tickets.
Stage ID	string	Yes	—	Stage ID within the pipeline.
Ticket Name	string	Yes	—	—
Additional Fields	collection	No	{}	—
— Associated Company IDs	string	No	—	Comma-separated company IDs to associate.
— Associated Contact IDs	string	No	—	Comma-separated contact IDs to associate.
— Category	string	No	—	Ticket category value.
— Close Date	dateTime	No	—	—
— Create Date	dateTime	No	—	—
— Description	string	No	—	—
— Priority	string	No	—	Ticket priority value.
— Resolution	string	No	—	—
— Source	string	No	—	—
— Ticket Owner ID	string	No	—	—

Ticket: Delete

Parameter	Type	Required	Default	Description
Ticket ID	string	Yes	—	—

Ticket: Get

Parameter	Type	Required	Default	Description
Ticket ID	string	Yes	—	—
Additional Fields	collection	No	{}	—
— Include Deleted	boolean	No	false	—
— Properties	string	No	—	Comma-separated property names.
— Properties with History	string	No	—	—

Ticket: Get Many

Parameter	Type	Required	Default	Description
Additional Fields	collection	No	{}	—
— Properties	string	No	—	—
— Properties with History	string	No	—	—
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)

Ticket: Update

Parameter	Type	Required	Default	Description
Ticket ID	string	Yes	—	—
Update Fields	collection	No	{}	—
— Associated Company IDs	string	No	—	—
— Associated Contact IDs	string	No	—	—
— Category	string	No	—	—
— Close Date	dateTime	No	—	—
— Create Date	dateTime	No	—	—
— Description	string	No	—	—
— Pipeline ID	string	No	—	—
— Priority	string	No	—	—
— Resolution	string	No	—	—
— Source	string	No	—	—
— Stage ID	string	No	—	—
— Ticket Name	string	No	—	—
— Ticket Owner ID	string	No	—	—

All Operations

Parameter	Type	Required	Default	Description
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

The HubSpot response is merged onto the input item JSON — the fields that arrived on the item stay on it, and any field HubSpot returns under the same name overwrites the incoming one. Binary data on the input item is forwarded unchanged.

How many items come out:

• Single-record operations — create, upsert, get, update, delete, add, remove — produce exactly one output item per input item.
• List operations — getAll, getRecentlyCreatedUpdated, search, searchByDomain — fan out: one output item per record returned, each carrying a copy of the input item’s fields. A result set with no matches produces no output item at all for that input item, so a downstream node can receive fewer items than this node was sent.

Delete returns no body from HubSpot, so the node emits a confirmation object instead:

{
  "vid": "12345",
  "deleted": true
}

vid is the ID you supplied — Contact ID, Company ID, Deal ID, Engagement ID or Ticket ID.

Everything else is the HubSpot API response spread onto the item exactly as HubSpot returned it; the node does not rename, flatten or filter it, so the available fields are whichever ones your HubSpot portal returns for that object (and whichever ones the Properties option asked for).

Operation	What lands on the item
upsert (Contact)	With Resolve Data on (the default), the full contact profile, carrying isNew from the write. With Resolve Data off, the create/update response.
delete (Contact, Company, Deal, Engagement)	The HubSpot response when there is one, otherwise the deleted confirmation shown above.
delete (Ticket)	Always the deleted confirmation shown above.
getAll, getRecentlyCreatedUpdated, search, searchByDomain	One item per record, each holding that record as HubSpot returned it.
All other operations	The HubSpot response object for the single record, spread onto the item.

Reference the result downstream by expression, e.g. {{ $json.vid }}.

Example Configuration

Create or update a contact from the email address on the incoming item, then read the full profile back:

{
  "type": "hubspot",
  "parameters": {
    "resource": "contact",
    "operation": "upsert",
    "email": "{{ $json.email }}",
    "additionalFields": {
      "firstName": "John",
      "lastName": "Doe",
      "jobTitle": "Marketing Manager",
      "companyName": "Acme Corp",
      "phoneNumber": "+1-555-0123",
      "city": "New York",
      "customPropertiesUi": {
        "customPropertiesValues": [
          { "property": "lead_source", "value": "website" }
        ]
      }
    },
    "options": {
      "resolveData": true
    }
  }
}

Search contacts by property, newest first, capped at 50 results:

{
  "type": "hubspot",
  "parameters": {
    "resource": "contact",
    "operation": "search",
    "filterGroupsUi": {
      "filterGroupsValues": [
        {
          "filtersUi": {
            "filterValues": [
              {
                "propertyName": "lifecyclestage",
                "operator": "EQ",
                "value": "marketingqualifiedlead"
              }
            ]
          }
        }
      ]
    },
    "additionalFields": {
      "sortBy": "createdate",
      "direction": "DESCENDING"
    },
    "returnAll": false,
    "limit": 50
  }
}

Create a company, naming it from the incoming item:

{
  "type": "hubspot",
  "parameters": {
    "resource": "company",
    "operation": "create",
    "name": "{{ $json.company }}",
    "additionalFields": {
      "companyDomainName": "acme.com",
      "industry": "Technology",
      "numberOfEmployees": 100,
      "annualRevenue": 5000000,
      "city": "San Francisco",
      "stateRegion": "CA",
      "websiteUrl": "https://acme.com"
    }
  }
}

Create a deal in a pipeline stage and associate it with a company:

{
  "type": "hubspot",
  "parameters": {
    "resource": "deal",
    "operation": "create",
    "stage": "appointmentscheduled",
    "additionalFields": {
      "dealName": "Acme Corp - Q1 Contract",
      "amount": "50000",
      "closeDate": "2024-03-31T23:59:59Z",
      "dealOwner": "12345",
      "associatedCompany": "67890",
      "dealType": "newbusiness"
    }
  }
}

Log a meeting engagement against a contact and a company:

{
  "type": "hubspot",
  "parameters": {
    "resource": "engagement",
    "operation": "create",
    "type": "meeting",
    "metadata": {
      "title": "Product Demo with Acme Corp",
      "body": "Product demonstration and requirements discussion",
      "startTime": "2024-02-15T14:00:00Z",
      "endTime": "2024-02-15T15:00:00Z",
      "internalMeetingNotes": "Client showed strong interest in enterprise features"
    },
    "additionalFields": {
      "associations": {
        "contactIds": "12345,67890",
        "companyIds": "54321"
      }
    }
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

HubSpot manages contacts, companies, deals, tickets, engagements and contact-list membership in a HubSpot CRM account. It is the right tool when a workflow must upsert, search, fetch or delete contacts, create, update or delete companies and search them by domain, create, update, search or delete deals, create, update or delete tickets, log or delete engagements, read recently changed records, or add and remove contacts on a list, rather than another CRM. It returns the affected or matching HubSpot records as JSON items, with getAll paging through lists.

Behavior notes

• Expressions resolve in the identifier fields only. {{ $json.field }} is evaluated for Email, Contact ID, Name, Company ID, Domain, Deal Stage, Deal ID, Type, Engagement ID, List ID, Pipeline ID, Stage ID, Ticket Name and Ticket ID. Anything you type inside a collection — Contact/Company/Deal Properties, Update Fields, Options, Filters, Filter Groups, Metadata — is sent to HubSpot exactly as written, so put expressions in the identifier fields, not in the collections.
• Engagement Create needs at least one Metadata field. An empty Metadata collection fails the item before any request is made.
• Search accepts at most three filter groups. Filters inside one group are combined with AND; separate groups are combined with OR.
• Ticket Get Many reads the whole ticket list and then applies Limit, so a small Limit makes the result shorter but not the call cheaper.

Common Patterns

• Bulk operations with pagination — for operations that return large datasets, always set Return All or a Limit deliberately, and narrow the payload with the Properties option.
• Custom properties — the Custom Properties collection works the same way on contacts, companies and deals: one Property Name / Value pair per custom field.
• Search with multiple filter groups — use several filter groups when you need OR logic between conditions, and several filters inside one group for AND logic.

Error Prevention Tips

1. Always specify required parameters for each operation type
2. Use correct data types - strings for IDs, numbers for numeric values, ISO 8601 for dates
3. Follow collection structures exactly - flat objects for collections, proper groupKeys for fixedCollections
4. Check display conditions - ensure parameter combinations are valid for the selected resource and operation
5. Use proper property names - refer to HubSpot documentation for exact custom property internal names