# HubSpot Cloud-Mode (Actions) Destination ## Destination Info * Accepts [Page](/docs/segment/connections/spec/page), [Alias](/docs/segment/connections/spec/alias), [Group](/docs/segment/connections/spec/group), [Identify](/docs/segment/connections/spec/identify), [Track](/docs/segment/connections/spec/track) calls. * Refer to it as **Hubspot Cloud Mode (actions)**, **Hubspot Cloud Mode (Actions)**, **HubSpot Cloud Mode (Actions)** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object) > \[!NOTE] > > This page is about the HubSpot Cloud-Mode (Actions) Destination. See below for information about other versions of the HubSpot destination: > > * [HubSpot Web (Actions)](/docs/segment/connections/destinations/catalog/actions-hubspot-web) > * [HubSpot (Classic)](/docs/segment/connections/destinations/catalog/hubspot) [HubSpot](https://www.hubspot.com/) 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](https://developers.hubspot.com/docs/api/overview). ## Things to know * 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, we recommend using the Event Tester or other tools to test and troubleshoot creating and updating companies in HubSpot. 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](/docs/segment/connections/destinations/catalog/hubspot/). > \[!WARNING] > > As of April 29, 2025, HubSpot no longer supports referencing custom object types by their base names. Instead, you must reference all custom objects by using their short-hand custom object type name, `fullyQualifiedName`, or `objectTypeId`. To avoid issues, update the following fields: > > * **Object Type** and **ObjectType to associate** in the **Upsert Custom Object Record** action > * **Object Type** in the **Custom Event V2** action > * **Object Type** and **To Object Type** in the **Custom Object V2** action > > For further details, refer to the [HubSpot documentation](https://developers.hubspot.com/changelog/breaking-change-removed-support-for-referencing-custom-object-types-by-base-name). ## 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](https://oauth.net/2/) 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](https://developers.hubspot.com/docs/api/analytics/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. > \[!NOTE] > > 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](https://knowledge.hubspot.com/settings/hubspot-user-permissions-guide#super-admin) in the HubSpot account to authenticate the connection. Click **Connect app**. ![Hubspot Scope Approval Screen.](https://docs-resources.prod.twilio.com/00f6aee52daa6d0cd46976801d83e2120fbeba0d1510653e03056334f0214cc0.png) 6. Follow the steps in the Destinations Actions documentation on [Customizing mappings](/docs/segment/connections/destinations/actions/#customize-mappings). 7. Enable the destination and configured mappings. > \[!NOTE] > > To ensure that data is sent downstream, configure and enable at least one mapping to handle a connected sources event(s). ## Actions v2 > \[!NOTE] > > If you are participating in HubSpot's [Sensitive Data in HubSpot CRM beta](https://developers.hubspot.com/sensitive-data), use the Custom Object v2 Action to send sensitive data to HubSpot. Segment's v2 Actions, [Custom Object v2](/docs/segment/connections/destinations/catalog/actions-hubspot-cloud/#custom-object-v2) and [Custom Event v2](/docs/segment/connections/destinations/catalog/actions-hubspot-cloud/#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. > \[!WARNING] > > 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 | Field | Description | Required | Type | | ------ | ----------------------------------- | -------- | ------ | | Hub ID | The Hub ID of your HubSpot account. | No | string | ## Available Actions Build your own Mappings. Combine supported [triggers](/docs/segment/connections/destinations/actions/#components-of-a-destination-action) with the following HubSpot Cloud Mode-supported actions: > \[!NOTE] > > Individual destination instances have support a maximum of 50 mappings. * [Send Custom Behavioral Event](#send-custom-behavioral-event) * [Upsert Custom Object Record](#upsert-custom-object-record) * [Upsert Contact](#upsert-contact-6) * [Upsert Company](#upsert-company) * [Custom Object V2](#custom-object-v2-1) * [Custom Event V2](#custom-event-v2-1) ### 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 | Required | Type | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -------- | | Event Name | 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\\_event\_name\`). Learn how to find the internal name in \[HubSpot’s documentation]\(https://knowledge.hubspot.com/analytics-tools/create-custom-behavioral-events). | Yes | STRING | | Event Timestamp | The time when this event occurred. If this isn't set, the current time will be used. | No | DATETIME | | Email Address | The email of the contact associated with this event. This is required if no user token or object ID is provided. | No | STRING | | User Token | The user token (utk) of the contact associated with this event. This is required if no email or object ID is provided. | No | STRING | | Object ID | 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. | No | STRING | | Event Properties | 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]\(https://knowledge.hubspot.com/analytics-tools/create-custom-behavioral-events#add-and-manage-event-properties). | No | OBJECT | ### 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 | Required | Type | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | Create Custom Object Record if Not Found | 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. | No | BOOLEAN | | Custom Object Search Fields | 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. | No | OBJECT | | Object Type | 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]\(https://developers.hubspot.com/docs/api/crm/crm-custom-objects#retrieve-existing-custom-objects). | Yes | STRING | | Properties | 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]\(https://knowledge.hubspot.com/crm-setup/manage-your-properties#create-custom-properties). | Yes | OBJECT | | Search Fields to Associate custom 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. | No | OBJECT | | ObjectType to associate | 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]\(https://developers.hubspot.com/docs/api/crm/crm-custom-objects#retrieve-existing-custom-objects). | No | STRING | | Association Label | Type of Association between two objectType | No | STRING | ### Upsert Contact Create or update a contact in HubSpot. Upsert Contact is a **Cloud** action. The default Trigger is `type = "identify"` | Field | Description | Required | Type | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | Email | 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. | Yes | STRING | | Company Name | The contact’s company. | No | STRING | | First Name | The contact’s first name. | No | STRING | | Last Name | The contact’s last name. | No | STRING | | Phone | The contact’s phone number. | No | STRING | | Street Address | The contact's street address, including apartment or unit number. | No | STRING | | City | The contact's city of residence. | No | STRING | | State | The contact's state of residence. | No | STRING | | Country | The contact's country of residence. | No | STRING | | Postal Code | The contact's zip code. | No | STRING | | Website | The contact’s company/other website. | No | STRING | | Lifecycle Stage | The contact’s stage within the marketing/sales process. See more information on default and custom stages in \[HubSpot’s documentation]\(https://knowledge.hubspot.com/contacts/use-lifecycle-stages). Segment supports moving status forwards or backwards. | No | STRING | | Other properties | 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]\(https://knowledge.hubspot.com/crm-setup/manage-your-properties#create-custom-properties). | No | OBJECT | | Send Batch Data to HubSpot | 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. | No | BOOLEAN | ### Upsert Company Create or update a company in HubSpot. Upsert Company is a **Cloud** action. The default Trigger is `type = "group"` | Field | Description | Required | Type | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | Unique Company Identifier | 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. | Yes | STRING | | Create Company if Not Found | 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. | Yes | BOOLEAN | | Associate Contact with Company | 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. | Yes | BOOLEAN | | Company Search Fields | 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. | No | OBJECT | | Company Name | The name of the company. | No | STRING | | Company Description | A short statement about the company’s mission and goals. | No | STRING | | Street Address | The street address of the company. | No | STRING | | City | The city where the company is located. | No | STRING | | State | The state or region where the company is located. | No | STRING | | Postal Code | The postal or zip code of the company. | No | STRING | | Domain | The company’s website domain. | No | STRING | | Phone | The company’s primary phone number. | No | STRING | | Number of Employees | The total number of people who work for the company. | No | INTEGER | | Industry | The type of business the company performs. | No | STRING | | Lifecycle Stage | The company’s stage within the marketing/sales process. See more information on default and custom stages in \[HubSpot’s documentation]\(https://knowledge.hubspot.com/contacts/use-lifecycle-stages). Segment supports moving status forwards or backwards. | No | STRING | | Other Properties | 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]\(https://knowledge.hubspot.com/crm-setup/manage-your-properties#create-custom-properties). Important: Do not use ’segment\_group\_id’ here as it is an internal property and will result in an an error. | No | OBJECT | ### 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. | Field | Description | Required | Type | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------ | | Object Details | Details of the object to associate the record with | Yes | OBJECT | | Properties | Properties to set on the record. | No | OBJECT | | Sensitive Properties | Sensitive Properties to set on the record. | No | OBJECT | | Associated Record Sync Mode | 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. | Yes | STRING | | Associations to add | Associations to create between the record and other records. | No | OBJECT | | Associations to remove (BETA) | Remove Association Labels from an Association between two records. Removing the default association label will dissociate both records from each other completely. This feature is currently in Beta and should not be used with production data. | No | OBJECT | | List Details (BETA) | Details of the list to add or remove the record from. This feature is currently in Beta and should not be used with production data. | No | OBJECT | | Timestamp | The time the event occurred. This will be used to de-duplicate the events before sending them to hubspot. | No | STRING | ### Custom Event V2 Send Custom Events to HubSpot Custom Event V2 is a **Cloud** action. | Field | Description | Required | Type | | ------------------------- | ------------------------------------------------- | -------- | -------- | | Event Name | The name of the event to send to Hubspot. | Yes | STRING | | Associated Record Details | Details of the record to associate the event with | Yes | OBJECT | | Properties | Properties to send with the event. | No | OBJECT | | Event Timestamp | The time when this event occurred. | No | DATETIME | ## Rate limits HubSpot's [API rate limit](https://developers.hubspot.com/docs/api/usage-details#rate-limits) 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, we recommend 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. > \[!NOTE] > > [HubSpot Associations](https://developers.hubspot.com/docs/api/crm/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, you must 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](https://app.hubspot.com/), 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 two 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 three 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, 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](https://developers.hubspot.com/docs/api/crm/deals), 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](https://developers.hubspot.com/docs/api/crm/associations). Note that 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](/docs/segment/connections/destinations/catalog/actions-hubspot-web/#track-page-view) is only available in [HubSpot Web (Actions) destination](/docs/segment/connections/destinations/catalog/actions-hubspot-web/). As a workaround, with HubSpot Cloud-Mode (Actions) destination, you can use the [Custom Behavioral Event](/docs/segment/connections/destinations/catalog/actions-hubspot-cloud/#send-custom-behavioral-event) to send Page events to Hubspot. Follow [Hubspot's instructions](https://knowledge.hubspot.com/analytics-tools/create-custom-behavioral-events-with-the-code-wizard) 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 the [HubSpot documentation](https://knowledge.hubspot.com/analytics-tools/create-custom-behavioral-events#define-the-api-call) 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](https://product.hubspot.com/blog/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 update companies in HubSpot if they never were associated with a `segment_group_id`? Segment uses the `segment_group_id` field to create and update companies in HubSpot. Records that were created from a pipeline outside of Segment won't have the `segment_group_id` field. If your companies aren't associated with a `segment_group_id`, you must use another field that uniquely identifies the company in HubSpot, like the `hs_object_id` field, to make updates to your companies. To use your unique field to update companies, navigate to your Upsert Company mapping and provide the key/value pair assosciated with the `hs_object_id` field in the Company Search fields section. ### How can I disable or delete a destination from Segment? Follow the instructions in the docs to [disable](/docs/segment/connections/destinations/actions/#disable-a-destination-action) or [delete](/docs/segment/connections/destinations/actions/#delete-a-destination-action) 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](https://knowledge.hubspot.com/integrations/connect-apps-to-hubspot#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](https://developers.hubspot.com/docs/api/crm/crm-custom-objects#properties) 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.