Menu

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.

In HubSpot, open Settings, then Integrations, then Private Apps, and click Create a private app.
On the Scopes tab, check the scopes your automations need: each core object family has its own pair (crm.objects.contacts.read and crm.objects.contacts.write, and likewise for companies, deals, and tickets), owner reads need crm.objects.owners.read, and list nodes need crm.lists.read or crm.lists.write.
Create the app and copy the access token from its Auth tab.
Scopes decide what the token can do, and the connection test does not exercise them: it calls an endpoint that needs no CRM scopes, so an under-scoped token connects cleanly and then returns 403 MISSING_SCOPES on exactly the nodes whose scopes were not checked. If that happens, add the missing scopes on the app's Scopes tab in HubSpot; the token string does not change when scopes change, so no reconnect is needed.

Connect HubSpot to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose HubSpot from the list.
Click Create new credential, paste the private app access token, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection: Mattering calls HubSpot's account details endpoint, which authenticates the token without requiring any CRM scopes.
Click Connect. All 50 HubSpot nodes appear in your canvas palette.

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
The token is invalid, was revoked (deleting the private app kills its token), or picked up stray whitespace when pasted. Copy the access token again from the app's Auth tab in HubSpot and update the credential on the connector.
Test Connection passes but a node returns 403 MISSING_SCOPES
The token is under-scoped. The connection test calls an endpoint that needs no CRM scopes, so it passes for every valid token regardless of which scope checkboxes were ticked at app creation. Run HubSpot: Get Token Scopes to see the token's actual granted scope list, then add the missing scopes on the app's Scopes tab in HubSpot. The token string does not change when scopes change, so the existing credential keeps working with no reconnect.
Fields you can see in HubSpot are missing from node responses
Reads return a small default property set unless you name properties explicitly, and engagement bodies such as hs_note_body are not in the default set. List the property names you need on the list, get, or search node; HubSpot: List Properties gives the exact internal names.
Creating a contact fails with a 409 duplicate error
HubSpot deduplicates contacts by email, and the 409 response includes the id of the existing record. Switch the workflow to HubSpot: Update Contact with idProperty set to email, or branch on the 409 to update instead of create. Companies deduplicate by domain the same way.
Adding records to a list is refused
The target is almost certainly a DYNAMIC list. Only MANUAL and SNAPSHOT lists accept membership writes; DYNAMIC lists compute membership from their filters and reject them by design. Use HubSpot: Search Lists with a processing-type filter to find MANUAL lists, or edit the dynamic list's filters in HubSpot itself.
A note, task, call, or email was logged but appears on no record
The engagement was created without an associations array. Engagements only surface on the timelines of the records they are associated to, so pass the target record ids at creation, with association type ids from HubSpot: List Association Labels. Re-run the create with associations, or find the orphan with the matching list node and note its id for cleanup.
An archived record needs to come back
Restore it in the HubSpot UI: archived contacts, companies, deals, and tickets sit in the recycling bin for 90 days and can be restored there, after which they are permanently deleted. There is no restore API, so no automation can undo an archive. If an archive node is reachable from a trigger, put a condition or approval step in front of it.
A logged email never arrived in anyone's inbox
HubSpot: Log Email records an email engagement on a record's timeline; it does not send email, and nothing in this integration does. Sending belongs to an email sending step elsewhere in the workflow; use the log node afterwards to record on the CRM timeline what was sent.

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.

Start Free Explore our Products