HubSpot Cloud Mode (Actions) Destination
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
- From the Segment web app, navigate to Connections > Catalog.
- Search for HubSpot Cloud Mode (Actions) in the Destinations Catalog, and select the destination.
- Click Configure HubSpot Cloud Mode (Actions).
- Select the source that will send data to HubSpot Cloud Mode (Actions) and follow the steps to name your destination.
- 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.
- Follow the steps in the Destinations Actions documentation on Customizing mappings.
- 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"
| Field | Description |
|---|---|
| Event Name* | Type: STRINGThe 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 |
| Event Timestamp | Type: DATETIMEThe time when this event occurred. If this isn’t set, the current time will be used. |
| Email Address | Type: STRINGThe email of the contact associated with this event. This is required if no user token or object ID is provided. |
| User Token | Type: STRINGThe user token (utk) of the contact associated with this event. This is required if no email or object ID is provided. |
| Object ID | Type: STRINGThe 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: OBJECTDefault 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.
| Field | Description |
|---|---|
| Create Custom Object Record if Not Found | Type: BOOLEANIf 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: OBJECTThe 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: STRINGThe 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: OBJECTProperties 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: OBJECTThe 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: STRINGThe 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: STRINGType 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"
| Field | Description |
|---|---|
| Email* | Type: STRINGThe 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: STRINGThe contact’s company. |
| First Name | Type: STRINGThe contact’s first name. |
| Last Name | Type: STRINGThe contact’s last name. |
| Phone | Type: STRINGThe contact’s phone number. |
| Street Address | Type: STRINGThe contact’s street address, including apartment or unit number. |
| City | Type: STRINGThe contact’s city of residence. |
| State | Type: STRINGThe contact’s state of residence. |
| Country | Type: STRINGThe contact’s country of residence. |
| Postal Code | Type: STRINGThe contact’s zip code. |
| Website | Type: STRINGThe contact’s company/other website. |
| Lifecycle Stage | Type: STRINGThe 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: OBJECTAny 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: BOOLEANIf 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"
| Field | Description |
|---|---|
| Unique Company Identifier* | Type: STRINGA 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: BOOLEANIf 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: BOOLEANIf 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: OBJECTThe 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: STRINGThe name of the company. |
| Company Description | Type: STRINGA short statement about the company’s mission and goals. |
| Street Address | Type: STRINGThe street address of the company. |
| City | Type: STRINGThe city where the company is located. |
| State | Type: STRINGThe state or region where the company is located. |
| Postal Code | Type: STRINGThe postal or zip code of the company. |
| Domain | Type: STRINGThe company’s website domain. |
| Phone | Type: STRINGThe company’s primary phone number. |
| Number of Employees | Type: INTEGERThe total number of people who work for the company. |
| Industry | Type: STRINGThe type of business the company performs. |
| Lifecycle Stage | Type: STRINGThe 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: OBJECTAny 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.
| Field | Description |
|---|---|
| Object Details* | Type: OBJECTDetails of the object to associate the record with |
| Properties | Type: OBJECTProperties to set on the record. |
| Sensitive Properties | Type: OBJECTSensitive Properties to set on the record. |
| Associated Record Sync Mode* | Type: STRINGSpecify 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: OBJECTAssociations to create between the record and other records. |
Custom Event V2
Send Custom Events to HubSpot
Custom Event V2 is a Cloud action.
| Field | Description |
|---|---|
| Event Name* | Type: STRINGThe name of the event to send to Hubspot. |
| Associated Record Details* | Type: OBJECTDetails of the record to associate the event with |
| Properties | Type: OBJECTProperties to send with the event. |
| Event Timestamp | Type: DATETIMEThe 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. |
FAQ and troubleshooting
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: 16 Sep 2024
Need support?
Questions? Problems? Need more info? Contact Segment Support for assistance!