Mattering Automations HubSpot integration
Connect HubSpot to Mattering Automations: contacts, companies, deals, tickets, search, associations, pipelines, engagements, and lists as workflow steps, authenticated with a HubSpot private app access token.
The Mattering Automations HubSpot integration adds HubSpot's CRM to your automation canvas: list, get, create, update, search, and archive contacts, companies, deals, and tickets; manage associations between records; read pipelines, stages, owners, and property definitions; log notes, tasks, calls, and emails on record timelines; and read lists plus add or remove members on manual lists. All 50 nodes are built on HubSpot's current date-based API surface (the 2026-03 release), the surface HubSpot is carrying forward as its legacy v3 and v4 paths head toward their announced sunset, and every route was confirmed against that current surface at build time.
Setup takes a few minutes: create a private app in HubSpot, choose its scopes, attach the access token as a credential in Mattering, and test the connection. This guide walks through each step and ends with the full node reference.
The one thing to understand before starting is the scope model. Private app tokens carry granular scopes chosen when the app is created, and the connection test uses an endpoint that needs no CRM scopes at all, so Test Connection can pass while individual nodes return 403 with category MISSING_SCOPES. That is the token working as configured, not a broken connector. HubSpot: Get Token Scopes returns the token's actual granted scope list, and scopes can be added to the app at any time without changing the token.
Before you start
- A HubSpot account. The free CRM tier works: private apps and the API are available on it, and developer test accounts provide full sandbox portals at no cost.
- Permission in that account to create private apps under Settings > Integrations > Private Apps.
- A Mattering workspace with access to the Automations app.
- A rough list of the object families your automations will touch, because private app scopes are chosen by checkbox at creation and an unchecked scope surfaces later as a 403.
Create a HubSpot private app token
Mattering authenticates to HubSpot with a private app access token, sent as a bearer credential on every request. Private apps are HubSpot's path for automating your own portal, with no OAuth flow involved; you choose the token's scopes by checkbox when creating the app.
Connect HubSpot to Mattering
Verify it works
After connecting, open any automation canvas and check the palette: a HubSpot section should list the query and action nodes. Drop HubSpot: Get Account Details onto the canvas and run a test step: it takes no configuration, needs no CRM scopes, and returns the portal id, account type, time zone, and currency of the account the token belongs to. Follow it with HubSpot: Get Token Scopes, which returns the token's actual granted scope list, so you know before building anything which nodes this credential can run.
To confirm the CRM surface itself, run HubSpot: List Properties for contacts. It doubles as the schema-discovery step every workflow benefits from, returning the internal property names the create, update, and search nodes expect. Then HubSpot: List Contacts confirms the contact read scope is in place. Everything in the verify path is read-only.
Node reference
50 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 29
HubSpot: Get Account Details
hubspot_get_account_details
Return the HubSpot account the token belongs to: portalId (hub id), account type, time zone, company currency, UI domain, and data hosting location. Needs no configuration and no CRM scopes, which makes it the connector's credential health check: a bad token fails here with a structured 401 before anything else runs.
HubSpot: Get Company
hubspot_get_company
Fetch one company by record id, or by a unique property value when idProperty is set (for example domain). Name the properties you need; the default set is small.
HubSpot: Get Contact
hubspot_get_contact
Fetch one contact by record id, or by a unique property value when idProperty is set (for example email). Name the properties you need; the default set is small.
HubSpot: Get Deal
hubspot_get_deal
Fetch one deal by record id, or by a unique property value when idProperty is set (for example a custom unique deal property). Name the properties you need; the default set is small.
HubSpot: Get List
hubspot_get_list
Fetch one list by its list id: name, object type, processing type (MANUAL, DYNAMIC, SNAPSHOT), size, and optionally its filter definition.
HubSpot: Get Owner
hubspot_get_owner
Fetch one owner by owner id, with email, name, userId, and team membership.
HubSpot: Get Property
hubspot_get_property
Fetch one property definition by internal name: type, field type, enumeration options, and whether it enforces unique values.
HubSpot: Get Ticket
hubspot_get_ticket
Fetch one ticket by record id, or by a unique property value when idProperty is set (for example a custom unique ticket property). Name the properties you need; the default set is small.
HubSpot: Get Token Scopes
hubspot_get_token_scopes
Return the private app token's metadata: hub id, app id, the acting user id, and the token's ACTUAL granted scope list. Private app scopes are chosen when the app is created, so a connected HubSpot account can still return 403 MISSING_SCOPES on individual nodes; run this node to see exactly which scopes the token carries. The response contains no credential material.
HubSpot: List Association Labels
hubspot_list_association_labels
List the association types defined between two object types (HubSpot-defined and custom labels), each with its typeId, category, and label. This is the schema-discovery node for the associationTypeId values used in record-create associations arrays.
HubSpot: List Associations
hubspot_list_associations
List the records of one type associated to a given record: each result carries the associated record id plus the association's category, type id, and label. Example: all deals associated to contact 512.
HubSpot: List Calls
hubspot_list_calls
List call engagements (object type id 0-48), cursor paginated. Ask for hs_call_title, hs_call_status, and hs_call_duration via properties.
HubSpot: List Companies
hubspot_list_companies
List company pages (object type id 0-2), cursor paginated via paging.next.after. Returns the default property set unless you name properties explicitly. For filtered reads use HubSpot: Search Companies instead. Requires the crm.objects.companies.read scope on the private app token.
HubSpot: List Contacts
hubspot_list_contacts
List contact pages (object type id 0-1), cursor paginated via paging.next.after. Returns the default property set unless you name properties explicitly. For filtered reads use HubSpot: Search Contacts instead. Requires the crm.objects.contacts.read scope on the private app token.
HubSpot: List Deals
hubspot_list_deals
List deal pages (object type id 0-3), cursor paginated via paging.next.after. Returns the default property set unless you name properties explicitly. For filtered reads use HubSpot: Search Deals instead. Requires the crm.objects.deals.read scope on the private app token.
HubSpot: List Logged Emails
hubspot_list_emails
List logged email engagements (object type id 0-49), cursor paginated. Ask for hs_email_subject and hs_email_status via properties.
HubSpot: List Memberships
hubspot_list_memberships
List the record ids that are members of a list, cursor paginated, with each record's membership timestamp. Feed the ids into Get Contact or a batch step downstream.
HubSpot: List Notes
hubspot_list_notes
List note engagements (object type id 0-46), cursor paginated. Ask for hs_note_body explicitly via properties; add associations=contacts to see which records each note sits on.
HubSpot: List Owners
hubspot_list_owners
List the account's owners (users records can be assigned to): id, email, name, and teams. Use the id value (not userId) in hubspot_owner_id properties. Requires the crm.objects.owners.read scope.
HubSpot: List Pipeline Stages
hubspot_list_pipeline_stages
List the stages of one pipeline in display order, with each stage's id, label, and metadata (deal win probability or ticket open/closed state). Use the stage ids when creating or moving deals and tickets.
HubSpot: List Pipelines
hubspot_list_pipelines
List every pipeline for an object type (deals or tickets, plus leads and some commerce objects on higher tiers), each with its stages inline. The id values here are what deal and ticket records store in their pipeline and stage properties.
HubSpot: List Properties
hubspot_list_properties
List every property defined on an object type, standard and custom: internal name, label, type, field type, group, and the options list for enumerations. This is the schema-discovery node: run it once to learn the exact property names the create, update, and search nodes expect.
HubSpot: List Tasks
hubspot_list_tasks
List task engagements (object type id 0-27), cursor paginated. Ask for hs_task_subject, hs_task_status, and hs_timestamp via properties to build due-date automations.
HubSpot: List Tickets
hubspot_list_tickets
List ticket pages (object type id 0-5), cursor paginated via paging.next.after. Returns the default property set unless you name properties explicitly. For filtered reads use HubSpot: Search Tickets instead. Requires the crm.objects.tickets.read scope on the private app token.
HubSpot: Search Companies
hubspot_search_companies
Search companies with property filters and free text. Searchable default text properties include name, domain, and phone. Filter groups OR together; filters inside a group AND together. Limits: 200 results per page, 10,000 results per query, and 5 search requests per second per account (shared across all search nodes). Archived records never appear; fresh writes can take a moment to be searchable.
HubSpot: Search Contacts
hubspot_search_contacts
Search contacts with property filters and free text. Searchable default text properties include email, firstname, lastname, phone, and company. Filter groups OR together; filters inside a group AND together. Limits: 200 results per page, 10,000 results per query, and 5 search requests per second per account (shared across all search nodes). Archived records never appear; fresh writes can take a moment to be searchable.
HubSpot: Search Deals
hubspot_search_deals
Search deals with property filters and free text. Searchable default text properties include dealname. Filter groups OR together; filters inside a group AND together. Limits: 200 results per page, 10,000 results per query, and 5 search requests per second per account (shared across all search nodes). Archived records never appear; fresh writes can take a moment to be searchable.
HubSpot: Search Lists
hubspot_search_lists
Search the account's lists by name. Filter by processing type to find the MANUAL lists that the membership add and remove nodes can write to (DYNAMIC lists are filter-driven and cannot be edited via the API).
HubSpot: Search Tickets
hubspot_search_tickets
Search tickets with property filters and free text. Searchable default text properties include subject and content. Filter groups OR together; filters inside a group AND together. Limits: 200 results per page, 10,000 results per query, and 5 search requests per second per account (shared across all search nodes). Archived records never appear; fresh writes can take a moment to be searchable.
Action nodes 21
HubSpot: Add List Members
hubspot_add_list_members
Add records to a MANUAL or SNAPSHOT list by record id. DYNAMIC lists are filter-driven and reject membership writes; edit their filters in HubSpot instead. Reversible via HubSpot: Remove List Members.
HubSpot: Archive Company
hubspot_archive_company
DESTRUCTIVE: archive (delete) a company. HubSpot moves the record to the recycling bin, where it can be restored in the HubSpot UI for 90 days; after that it is permanently deleted. There is no restore API, so treat this as a delete in automations.
HubSpot: Archive Contact
hubspot_archive_contact
DESTRUCTIVE: archive (delete) a contact. HubSpot moves the record to the recycling bin, where it can be restored in the HubSpot UI for 90 days; after that it is permanently deleted. There is no restore API, so treat this as a delete in automations.
HubSpot: Archive Deal
hubspot_archive_deal
DESTRUCTIVE: archive (delete) a deal. HubSpot moves the record to the recycling bin, where it can be restored in the HubSpot UI for 90 days; after that it is permanently deleted. There is no restore API, so treat this as a delete in automations.
HubSpot: Archive Ticket
hubspot_archive_ticket
DESTRUCTIVE: archive (delete) a ticket. HubSpot moves the record to the recycling bin, where it can be restored in the HubSpot UI for 90 days; after that it is permanently deleted. There is no restore API, so treat this as a delete in automations.
HubSpot: Create Association
hubspot_create_association
Associate two existing records with the default (unlabeled) association type for the pair, for example link contact 512 to company 1024. For labeled associations use the association type ids from HubSpot: List Association Labels via the extra-body pattern on record create/update instead.
HubSpot: Create Company
hubspot_create_company
Create a company. Properties go in one JSON object keyed by internal property name; associate it to existing records in the same call via the associations array. Requires the crm.objects.companies.write scope.
HubSpot: Create Contact
hubspot_create_contact
Create a contact. Properties go in one JSON object keyed by internal property name; associate it to existing records in the same call via the associations array. Requires the crm.objects.contacts.write scope.
HubSpot: Create Deal
hubspot_create_deal
Create a deal. Properties go in one JSON object keyed by internal property name; associate it to existing records in the same call via the associations array. Requires the crm.objects.deals.write scope.
HubSpot: Create Note
hubspot_create_note
Log a note on the CRM timeline and pin it to records via the associations array (a note without associations appears on no record). hs_timestamp is required and places the note on the timeline.
HubSpot: Create Task
hubspot_create_task
Create a CRM task. hs_timestamp is required and is the task's DUE date; assign it with hubspot_owner_id and attach it to records via the associations array.
HubSpot: Create Ticket
hubspot_create_ticket
Create a ticket. Properties go in one JSON object keyed by internal property name; associate it to existing records in the same call via the associations array. Requires the crm.objects.tickets.write scope.
HubSpot: Log Call
hubspot_create_call
Log a call engagement on the CRM timeline (records that a call happened; does not place calls). hs_timestamp is required; attach the call to records via the associations array.
HubSpot: Log Email
hubspot_log_email
Log an email engagement on the CRM timeline. This RECORDS an email that was sent or received elsewhere; it does NOT send email. hs_timestamp is required; attach it to records via the associations array.
HubSpot: Remove Association
hubspot_remove_association
Remove ALL associations between two records (both records themselves are untouched). Reversible: re-creating the association restores the link, though custom labels must be re-applied.
HubSpot: Remove List Members
hubspot_remove_list_members
Remove records from a MANUAL or SNAPSHOT list by record id. The records themselves are untouched; only the list membership changes, and re-adding restores it exactly.
HubSpot: Update Company
hubspot_update_company
Update a company by record id (or by a unique property via idProperty). Partial update: only the properties you send change; clear a property by sending an empty string for it.
HubSpot: Update Contact
hubspot_update_contact
Update a contact by record id (or by a unique property via idProperty). Partial update: only the properties you send change; clear a property by sending an empty string for it.
HubSpot: Update Deal
hubspot_update_deal
Update a deal by record id (or by a unique property via idProperty). Partial update: only the properties you send change; clear a property by sending an empty string for it.
HubSpot: Update Task
hubspot_update_task
Update a task: complete it ({"hs_task_status": "COMPLETED"}), reassign it, change its due date, or edit its text. Partial update; only named properties change.
HubSpot: Update Ticket
hubspot_update_ticket
Update a ticket by record id (or by a unique property via idProperty). Partial update: only the properties you send change; clear a property by sending an empty string for it.
Using the integration
On the automation canvas
HubSpot nodes chain with every other node: a scheduled HubSpot: Search Deals sweep can open prep tasks in Mattering Productivity when deals enter a stage, and a HubSpot: Search Contacts sweep can sync new and changed contacts into a Mattering database for reporting. Mattering Sales is the platform's native CRM; this integration is for teams already living in HubSpot who want that data working on the same canvas as the rest of their automations.
From AI assistants over MCP
Every node speaks MCP, the open protocol for connecting AI assistants to tools. Claude, ChatGPT, and Matter can search records, read pipelines, and log engagements through the same nodes your workflows use. Point an agent at HubSpot: List Properties first: it returns the property names and types the rest of the surface expects, which is the difference between an agent that guesses field names and one that knows them.
Search, the filter grammar, and polling
HubSpot: Search Contacts, HubSpot: Search Companies, HubSpot: Search Deals, and HubSpot: Search Tickets carry HubSpot's full grammar: filter groups OR together, filters inside a group AND together, up to 5 groups of 6 filters (18 total), operators from EQ through BETWEEN, IN, and CONTAINS_TOKEN, and at most one sort rule. Limits: 200 results per page, 10,000 results per query, and 5 search requests per second per account, shared across all four search nodes. Archived records never appear, IN and NOT_IN string values must be lowercase, and fresh writes take a short indexing delay to become searchable. There is no inbound HubSpot trigger in this integration, so polling is the pattern: run a search on a schedule with a last-modified date filter and act on what changed.
Everything goes through properties
Create and update bodies nest all values in one properties object keyed by internal property name, which is why HubSpot: List Properties is the first node to run against any object type. Updates are partial: only the properties you send change, and sending an empty string clears one. HubSpot deduplicates contacts by email (a duplicate create returns 409 with the existing record id) and companies by domain; deals have no dedupe key. Required properties: deals need dealname, tickets need subject and hs_pipeline_stage, and every engagement needs hs_timestamp.
Engagements are timeline records
HubSpot: Create Note, HubSpot: Create Task, HubSpot: Log Call, and HubSpot: Log Email write engagements onto CRM timelines, and each needs an associations array to appear anywhere: an engagement created without associations exists but shows on no record. Association type ids differ per direction, and HubSpot: List Association Labels is the authoritative lookup. Two nodes deserve plain words: the log-email node records an email that was sent or received elsewhere and never sends one, and the log-call node records that a call happened and never places one. On tasks, hs_timestamp is the due date; on notes, calls, and emails it is the timeline position.
Archives and list membership, honestly
The four archive nodes (HubSpot: Archive Contact, HubSpot: Archive Company, HubSpot: Archive Deal, HubSpot: Archive Ticket) move records to HubSpot's recycling bin, restorable in the HubSpot UI for 90 days and permanently deleted after; there is no restore API, so automations should treat archive as delete and gate it accordingly. On lists, HubSpot: Add List Members and HubSpot: Remove List Members work on MANUAL and SNAPSHOT lists only: DYNAMIC lists are filter-driven and reject membership writes, and HubSpot: Search Lists can filter by processing type to find the lists a workflow can actually edit.
Troubleshooting
Test Connection fails with a 401
Test Connection passes but a node returns 403 MISSING_SCOPES
Fields you can see in HubSpot are missing from node responses
Creating a contact fails with a 409 duplicate error
Adding records to a list is refused
A note, task, call, or email was logged but appears on no record
An archived record needs to come back
A logged email never arrived in anyone's inbox
Related
The HubSpot MCP
What connecting HubSpot unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
HubSpot is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.