HubSpot Cloud Mode (Actions) Destination

On this page

Destination Info

Additional versions of this destination are available

This page is about the HubSpot Cloud Mode (Actions) Destination. See below for information about other versions of the HubSpot destination:

HubSpot is an all-in-one marketing tool that helps attract new leads and converts them into paying customers, with features like landing page creation and email automation.

When you use the HubSpot Cloud Mode (Actions) destination, Segment sends your data to HubSpot’s REST API.

The Upsert Company action is not compatible with the Mapping Tester on the mappings page if Associate Contact is set to Yes. As a result, Segment recommends using the Event Tester or other tools to test and troubleshoot creating and updating companies in HubSpot.

Note that for the company to contact association to work, you are required to trigger an Upsert Contact action before triggering an Upsert Company action. Contacts created with batch endpoint can not be associated to a Company from the Upsert Company Action.

Behavioral Events (Legacy) are only supported with Hubspot Classic Destination.

Benefits of HubSpot Cloud Mode (Actions) vs HubSpot Classic

HubSpot Cloud Mode (Actions) provides the following benefits over the classic HubSpot destination:

  • Fewer settings. Data mapping for actions-based destinations happens during configuration, which eliminates the need for most settings.
  • Clearer mapping of data. Actions-based destinations enable you to define the mapping between the data Segment receives from your source, and the data Segment sends to the destination.
  • Granular control over data sent. You can customize the conditions under which the events are sent to HubSpot.
  • OAuth 2.0 support. Authentication with HubSpot uses OAuth 2.0 instead of an API key.
  • Sandbox support. Test with a HubSpot sandbox account before implementing in your main production account to feel confident in your configuration.
  • Support for custom behavioral events. Send custom behavioral events and event properties to HubSpot.
  • Create records in custom objects. Use your Segment events to create records in any standard or custom object in your HubSpot account.

A HubSpot Enterprise Marketing Hub account is required to send Custom Behavioral Events.

Getting started

  1. From the Segment web app, navigate to Connections > Catalog.
  2. Search for HubSpot Cloud Mode (Actions) in the Destinations Catalog, and select the destination.
  3. Click Configure HubSpot Cloud Mode (Actions).
  4. Select the source that will send data to HubSpot Cloud Mode (Actions) and follow the steps to name your destination.
  5. On the Settings tab, authenticate with HubSpot using OAuth. Your user must be a super admin in the HubSpot account to authenticate the connection. Click Connect app. Hubspot Scope Approval Screen
  6. Follow the steps in the Destinations Actions documentation on Customizing mappings.
  7. Enable the destination and configured mappings.

To ensure that data is sent downstream, configure and enable at least one mapping to handle a connected sources event(s).

Actions v2

You can use the Custom Object v2 Action to send Sensitive Data to HubSpot

If you are participating in HubSpot’s Sensitive Data in HubSpot CRM beta, use the Custom Object v2 Action to send sensitive data to HubSpot.

Segment’s v2 Actions, Custom Object v2 and Custom Event v2, support the following features:

  • Sync modes: Control how Segment updates your downstream destination by selecting a sync mode, or a strategy for updating your downstream data
  • Dynamic dropdowns: When creating or updating a mapping in the Segment app, the dropdown auto-populates all of the available properties directly from HubSpot.
  • Create and modify data: Use Sync modes to create objects in your downstream destination without having to leave the Segment app.

You might need to reauthorize your HubSpot account to use all of the features associated with v2 Actions.

Sync modes

Sync modes allow users to define how Segment should update the data in your destination.

Available sync modes for the Custom Object v2 and Custom Event v2 Actions include:

  • Update: Modify existing records in the destination without adding new ones.
  • Upsert: Update existing records and add new ones, if necessary.
  • Add: Add records to a list, segment, or journey.

Destination Settings

Setting Description
Hub ID

The Hub ID of your HubSpot account.

Available Actions

Build your own Mappings. Combine supported triggers with the following HubSpot Cloud Mode-supported actions:

Mapping limits per destination

Individual destination instances have support a maximum of 50 mappings.

Send Custom Behavioral Event

Send a custom behavioral event to HubSpot.

Send Custom Behavioral Event is a Cloud action. The default Trigger is: type = "track"

Click to show / hide fields

Field Description
Event Name* Type: STRING

The internal event name assigned by HubSpot. This can be found in your HubSpot account. Events must be predefined in HubSpot. Please input the full internal event name including the pe prefix (i.e. pe<HubID>_event_name). Learn how to find the internal name in HubSpot’s documentation.
Event Timestamp Type: DATETIME

The time when this event occurred. If this isn’t set, the current time will be used.
Email Address Type: STRING

The email of the contact associated with this event. This is required if no user token or object ID is provided.
User Token Type: STRING

The user token (utk) of the contact associated with this event. This is required if no email or object ID is provided.
Object ID Type: STRING

The ID of the object associated with this event. This can be the HubSpot contact ID, company ID, or ID of any other object. This is required if no email or user token is provided.
Event Properties Type: OBJECT

Default or custom properties that describe the event. On the left-hand side, input the internal name of the property as seen in your HubSpot account. On the right-hand side, map the Segment field that contains the value. See more information in HubSpot’s documentation.

Upsert Custom Object Record

Upsert records of Deals, Tickets or other Custom Objects in HubSpot.

Upsert Custom Object Record is a Cloud action.

Click to show / hide fields

Field Description
Create Custom Object Record if Not Found Type: BOOLEAN

If true, Segment will attempt to update an existing custom object record in HubSpot and if no record is found, Segment will create a new custom object record. If false, Segment will only attempt to update an existing record and never create a new record. This is set to true by default.
Custom Object Search Fields Type: OBJECT

The unique field(s) used to search for an existing record in HubSpot to update. The fields provided here are then used to search. If a custom object is still not found, a new one is created.
Object Type* Type: STRING

The CRM object schema to use for creating a record. This can be a standard object (i.e. tickets, deals) or fullyQualifiedName of a custom object. Schema for the Custom Objects must be predefined in HubSpot. More information on Custom Objects and fullyQualifiedName in HubSpot documentation.
Properties* Type: OBJECT

Properties to send to HubSpot. On the left-hand side, input the internal name of the property as seen in your HubSpot account. On the right-hand side, map the Segment field that contains the value. Please make sure to include the object’s required properties. Any custom properties must be predefined in HubSpot. More information in HubSpot documentation.
Search Fields to Associate custom Object Type: OBJECT

The unique field(s) used to search for an existing custom record in HubSpot to get toObjectId so that segment will associate the record with this record. If a Record is not found on the basis of data provided here in key:value format will skip the association.
ObjectType to associate Type: STRING

The CRM object schema to use for associating a record. This can be a standard object (i.e. tickets, deals, contacts, companies) or fullyQualifiedName of a custom object. Schema for the Custom Objects must be predefined in HubSpot. More information on Custom Objects and fullyQualifiedName in HubSpot documentation.
Association Label Type: STRING

Type of Association between two objectType

Upsert Contact

Create or update a contact in HubSpot.

Upsert Contact is a Cloud action. The default Trigger is: type = "identify"

Click to show / hide fields

Field Description
Email* Type: STRING

The contact’s email. Email is used to uniquely identify contact records in HubSpot. If an existing contact is found with this email, we will update the contact. If a contact is not found, we will create a new contact.
Company Name Type: STRING

The contact’s company.
First Name Type: STRING

The contact’s first name.
Last Name Type: STRING

The contact’s last name.
Phone Type: STRING

The contact’s phone number.
Street Address Type: STRING

The contact’s street address, including apartment or unit number.
City Type: STRING

The contact’s city of residence.
State Type: STRING

The contact’s state of residence.
Country Type: STRING

The contact’s country of residence.
Postal Code Type: STRING

The contact’s zip code.
Website Type: STRING

The contact’s company/other website.
Lifecycle Stage Type: STRING

The contact’s stage within the marketing/sales process. See more information on default and custom stages in HubSpot’s documentation. Segment supports moving status forwards or backwards.
Other properties Type: OBJECT

Any other default or custom contact properties. On the left-hand side, input the internal name of the property as seen in your HubSpot account. On the right-hand side, map the Segment field that contains the value. Custom properties must be predefined in HubSpot. See more information in HubSpot’s documentation.
Send Batch Data to HubSpot Type: BOOLEAN

If true, Segment will batch events before sending to HubSpot’s API endpoint. HubSpot accepts batches of up to 100 events. Note: Contacts created with batch endpoint can’t be associated to a Company from the UpsertCompany Action.

Upsert Company

Create or update a company in HubSpot.

Upsert Company is a Cloud action. The default Trigger is: type = "group"

Click to show / hide fields

Field Description
Unique Company Identifier* Type: STRING

A unique identifier you assign to a company. Segment creates a custom property in HubSpot to store this value for each company so it can be used as a unique search field. Segment recommends not changing this value once set to avoid creating duplicate companies.
Create Company if Not Found* Type: BOOLEAN

If true, Segment will attempt to update an existing company in HubSpot and if no company is found, Segment will create a new company. If false, Segment will only attempt to update an existing company and never create a new company. This is set to true by default.
Associate Contact with Company* Type: BOOLEAN

If true, Segment will associate the company with the user identified in your payload. If no contact is found in HubSpot, an error is thrown and the company is not created/updated. If false, Segment will not attempt to associate a contact with the company and companies can be created/updated without requiring a contact association. This is set to true by default.
Company Search Fields Type: OBJECT

The unique field(s) used to search for an existing company in HubSpot to update. By default, Segment creates a custom property to store groupId for each company and uses this property to search for companies. If a company is not found, the fields provided here are then used to search. If a company is still not found, a new one is created.
Company Name Type: STRING

The name of the company.
Company Description Type: STRING

A short statement about the company’s mission and goals.
Street Address Type: STRING

The street address of the company.
City Type: STRING

The city where the company is located.
State Type: STRING

The state or region where the company is located.
Postal Code Type: STRING

The postal or zip code of the company.
Domain Type: STRING

The company’s website domain.
Phone Type: STRING

The company’s primary phone number.
Number of Employees Type: INTEGER

The total number of people who work for the company.
Industry Type: STRING

The type of business the company performs.
Lifecycle Stage Type: STRING

The company’s stage within the marketing/sales process. See more information on default and custom stages in HubSpot’s documentation. Segment supports moving status forwards or backwards.
Other Properties Type: OBJECT

Any other default or custom company properties. On the left-hand side, input the internal name of the property as seen in your HubSpot account. On the right-hand side, map the Segment field that contains the value. Custom properties must be predefined in HubSpot. See more information in HubSpot’s documentation. Important: Do not use ’segment_group_id’ here as it is an internal property and will result in an an error.

Custom Object V2

Add, create or update records of any Object type to HubSpot, and optionally assocate that record with other records of any Object type.

Custom Object V2 is a Cloud action.

You can use the Custom Object v2 Action to make multiple assosciations

For more information, see HubSpot’s Associate records documentation.

Click to show / hide fields

Field Description
Object Details* Type: OBJECT

Details of the object to associate the record with
Properties Type: OBJECT

Properties to set on the record.
Sensitive Properties Type: OBJECT

Sensitive Properties to set on the record.
Associated Record Sync Mode* Type: STRING

Specify if Segment create associated records in Hubspot. Records will only be created if the record requires a single identifier field and does not require property fields to be set upon creation.
Associations Type: OBJECT

Associations to create between the record and other records.

Custom Event V2

Send Custom Events to HubSpot

Custom Event V2 is a Cloud action.

Click to show / hide fields

Field Description
Event Name* Type: STRING

The name of the event to send to Hubspot.
Associated Record Details* Type: OBJECT

Details of the record to associate the event with
Properties Type: OBJECT

Properties to send with the event.
Event Timestamp Type: DATETIME

The time when this event occurred.

Rate limits

HubSpot’s API rate limit is 100 API calls per 10 seconds. While Segment implements retries for temporary issues, large data volumes sent simultaneously might exceed this limit and result in incomplete data transmission.

For customers with substantial data volumes, Segment recommends segmenting the data into smaller batches and scheduling transfers over an extended period of time. This approach ensures successful data transmission to HubSpot without encountering rate limits.

HubSpot Associations might exacerbate rate limit issues

HubSpot Associations often require additional API calls. When working with Associations, carefully plan your strategy and consider a more gradual approach to creating them, especially for large datasets, to avoid reaching your API call limit.

Support for association between two custom object records in upsert custom object records

To associate two records, it’s mandatory to have these three fields: Search Fields to associate , ObjectType to associate, and Association Label. If any of these three fields aren’t configured, the association skips.

Field Details
Search Fields to associate This finds a unique record of custom object based on key-value search properties so that records can be associated together.
* An association record fails if there is more than one record returned from the search association object.
* An association skips if no record is found with the data provided in key:value format.
ObjectType to associate To associate the newly created and updated custom object record with another object type, select the object type you want it to be associated with.
Association Label Select an association label between both the object types. From the HubSpot Dashboard, you can create associations between any type of object. To create an association label:
1. Log in to the HubSpot Dashboard.
2. Go to Data Management > Objects > Custom Objects.
3. Go to the Associations tab and click Create association label.

FAQs and troubleshooting

Why am I receiving a Contact already exists error?

This error only applies to integrations with 2 mappings that can create profiles in HubSpot. Initially, the Upsert Contact action seeks to update an existing contact. If no contact is found, a subsequent attempt is made to create a new contact, potentially leading to 3 separate HubSpot API requests. For example, an Expired Authentication error may occur if the token expires on the initial request, prompting a token refresh and a subsequent request. If the next error indicates resource not found, it means the contact wasn’t located, leading to a second attempt to create the contact. However, this attempt might fail due to a Conflict error, suggesting the contact already exists. This situation can arise if you activate another mapping, which causes the contact to be created by the time the Upsert Contact Action attempts its final contact creation request, due to the Custom Behavioral Event Action being triggered as well.

How do I send other standard objects to HubSpot?

Segment provides prebuilt mappings for contacts and companies. If there are other standard objects you would like to create records in, please use the Create Custom Object Record action. For example, to create a deal in HubSpot, add a mapping for Create Custom Object Record, set up your Event Trigger criteria, and input a literal string of “deals” as the Object Type. You can use the Properties object to add fields that are in the deals object, such as dealname and dealstage. The same can be done with other object types (for example, tickets, quotes, etc). Ending fields that are to go to HubSpot outside of the properties object isn’t supported. This includes sending associations. Please note, Segment only supports creating new records in these cases; updates to existing records are only supported for contacts and companies.

How do I send Page events to HubSpot?

The Track Page View action is only available in HubSpot Web (Actions) destination. As a workaround, with HubSpot Cloud Mode (Actions) destination, you can use the Custom Behavioral Event to send Page events to Hubspot. You’ll need to follow Hubspot’s instructions to create a custom behavioral event for Page Viewed in HubSpot.

Why aren’t my custom behavioral events appearing in HubSpot?

HubSpot has several limits for custom behavioral events, including a limit on the number of event properties per event. Each event can contain data for up to 50 properties. If this limit is exceeded, the request will fail. See HubSpot documentation for other limits.

How do I resolve a 403 error for custom behavioral events?

403 errors indicate that Segment is unable to send your event to HubSpot because the account connected doesn’t have sufficient permissions. If you’re observing 403 errors for Custom Behavioral Events, ensure that your HubSpot account is a HubSpot Enterprise Marketing Hub account. After upgrading your account to Enterprise Marketing Hub, Reauthorize from the Settings page of your destination to resolve the 403 errors.

Why can’t I set an entire object for the Other properties field?

This destination doesn’t allow selecting an entire object for the Other properties field. HubSpot rejects API calls if a property name doesn’t match with HubSpot’s internal name. When working with a large object of key/value pairs, map each key/value pair to prevent rejection. This ensures that every key matches the pre-created property names in HubSpot.

Does the HubSpot Cloud Mode (Actions) destination support EU data residency?

Yes. HubSpot will automatically redirect API requests directly to an EU data center if your HubSpot instance is on an EU data center. See more in HubSpot’s Routing API Traffic article.

How do I attribute a custom behavioral event with a user token instead of Email?

Event payloads should contain an email with either a valid format, empty string, or a null value. As a result, the user token takes precedence and is validated in a Send custom behavioral event mapping. Segment can’t deliver the event to your destination if the email is invalid.

How can I disable or delete a destination from Segment?

Follow the instructions in the docs to disable or delete a destination action from Segment.

How can I uninstall an app from my HubSpot account?

Follow the steps outlined in HubSpot’s Uninstall an app docs to uninstall or disconnect an app from your HubSpot account.

How does disconnecting and uninstalling affect a user’s data and HubSpot account?

Segment immediately stops sending data to HubSpot after you disconnect and uninstall a HubSpot account.

Understanding HubSpot’s date and dateTime` custom property types

If you plan on sending a date value that includes time data to your mapped HubSpot custom properties, select HubSpot’s dateTime property type in HubSpot. If you plan to send a date value that does not contain time data, select the date property value in HubSpot. For more information about custom property types, see HubSpot’s Custom objects documentation.

If you send a date value that contains time data to a custom property in HubSpot with a date property type, the event might fail due to an “Invalid Date Error.”

Both of HubSpot’s date property types each accept ISO 8601 formatted values, but only the dateTime property type accepts values that include time data.

This page was last modified: 13 Dec 2024

Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
or
Create free account

Was this page helpful?