HubSpot

Manage HubSpot companies, contacts, and deals from inside an agent workflow.

HubSpot actions let an agent work with CRM records directly in a flow. An agent can create and read companies, search and upsert contacts, and create and list deals, then pass the results to later steps.

Supported actions

Group	Actions
Companies	Create, Get, Get All
Contacts	Get, Get All, Search, Upsert, Delete
Deals	Create, Get, Get All

Prerequisites

Create a HubSpot credential

Generate a private app access token in HubSpot, then store it as a HubSpot credential in Credential Management. Select that credential on every HubSpot action.

How to use these actions

• Map text inputs from earlier steps. Text inputs accept a value mapped from a previous step. The Limit and Amount inputs take fixed values.
• Choose which properties to return. The Properties input is a comma separated list of properties. Leave it empty to return the default set.
• Page through results with the cursor. The Get All and Search actions return an After cursor. Pass that cursor into After on the next call to fetch the following page.
• Upsert matches contacts by email. Contact Upsert creates a contact when no match exists and updates the existing contact when the email is already in HubSpot.

Actions

Companies

HubSpot Company Create

Creates a new company.

Input	Required	Description
Name	Yes	The company name.
Domain	No	The company domain, for example example.com.
Industry	No	The company’s industry.
Phone	No	The company’s phone number.
City	No	The company’s city.
State	No	The company’s state or region.
Country	No	The company’s country.
Description	No	A description of the company.

HubSpot Company Get

Retrieves a company by ID.

Input	Required	Description
Company ID	Yes	The unique identifier of the company to retrieve.
Properties	No	A comma separated list of properties to return. Leave empty for the default set.

HubSpot Company Get All

Lists companies.

Input	Required	Description
Limit	No	Maximum number of companies to return, from 1 to 100. Defaults to 100.
Properties	No	A comma separated list of properties to return. Leave empty for the default set.
After	No	Pagination cursor returned by the previous request.

Contacts

HubSpot Contact Get

Retrieves a contact by ID.

Input	Required	Description
Contact ID	Yes	The unique identifier of the contact to retrieve.
Properties	No	A comma separated list of properties to return. Leave empty for the default set.

HubSpot Contact Get All

Lists contacts.

Input	Required	Description
Limit	No	Maximum number of contacts to return, from 1 to 100. Defaults to 100.
Properties	No	A comma separated list of properties to return. Leave empty for the default set.
After	No	Pagination cursor returned by the previous request.

HubSpot Contact Search

Searches for contacts.

Input	Required	Description
Query	Yes	The search query to match contacts against.
Limit	No	Maximum number of results to return, from 1 to 100. Defaults to 10.
Properties	No	A comma separated list of properties to return. Leave empty for the default set.
After	No	Pagination cursor returned by the previous request.

HubSpot Contact Upsert

Creates a contact, or updates the existing contact matched by email.

Input	Required	Description
Email	Yes	The contact’s email address. Used to match an existing contact for the upsert.
First Name	No	The contact’s first name.
Last Name	No	The contact’s last name.
Phone	No	The contact’s phone number.
Company	No	The contact’s company.
Website	No	The contact’s website.
Job Title	No	The contact’s job title.
Lifecycle Stage	No	One of subscriber, lead, marketingqualifiedlead, salesqualifiedlead, opportunity, customer, evangelist, or other.

HubSpot Contact Delete

Deletes a contact.

Input	Required	Description
Contact ID	Yes	The unique identifier of the contact to delete.

Deals

HubSpot Deal Create

Creates a new deal.

Input	Required	Description
Deal Name	Yes	The deal name.
Deal Stage	No	The deal stage, for example appointmentscheduled, qualifiedtobuy, closedwon, or closedlost.
Pipeline	No	The pipeline ID the deal belongs to.
Amount	No	The monetary amount, entered as a fixed number.
Close Date	No	The close date in ISO 8601 format.
Deal Type	No	The deal type, for example newbusiness or existingbusiness.
Description	No	A description of the deal.

HubSpot Deal Get

Retrieves a deal by ID.

Input	Required	Description
Deal ID	Yes	The unique identifier of the deal to retrieve.
Properties	No	A comma separated list of properties to return. Leave empty for the default set.

HubSpot Deal Get All

Lists deals.

Input	Required	Description
Limit	No	Maximum number of deals to return, from 1 to 100. Defaults to 100.
Properties	No	A comma separated list of properties to return. Leave empty for the default set.
After	No	Pagination cursor returned by the previous request.

Example

An agent that turns an inbound inquiry into a tracked deal:

1. Find or create the contact

   A HubSpot Contact Upsert action maps Email from the inquiry and sets First Name, Last Name, and Company, creating the contact if it does not already exist.

2. Find the company

   A HubSpot Contact Search action runs a Query for the company domain so a model step can confirm related records.

3. Create the deal

   A HubSpot Deal Create action sets Deal Name, Deal Stage to appointmentscheduled, and Amount from the inquiry value.

4. Confirm

   A model step summarizes the contact and deal, including their returned IDs, for the activity log.

Troubleshooting

Authentication failed

Confirm the stored token is a valid private app access token and has not been rotated. Regenerate it in HubSpot and update the credential if needed.

Missing scopes for this object

The private app must grant the CRM scopes for the object you are calling, such as read and write access to companies, contacts, or deals. Update the app’s scopes in HubSpot.

Upsert created a duplicate

Contact Upsert matches on Email. A different or misspelled email creates a new contact instead of updating the intended one. Confirm the email matches the existing record exactly.

Pagination returns the same page

Pass the After cursor from the previous response into the next call. Reusing an empty or stale cursor returns the first page again.

For issues common to every vendor, see the Actions overview.