HubSpot Cloud Mode Integration (New API v3)

RudderStack supports the following API calls while sending data to Hubspot via cloud mode using the new API.

This documentation is written for HubSpot API v3.

Currently, RudderStack does not support the new datetime data type introduced by HubSpot.

Identify

RudderStack sends the identify call to check if a contact exists, if it does, RudderStack updates the contact with new information. Otherwise, it creates a new contact.

A sample identify call is as shown:

rudderanalytics.identify({
  firstName: "Alex",
  city: "New Orleans",
  country: "USA",
  phone: "+1-202-555-0146",
  email: "alex@example.com",
  custom_flavor: "chocolate",
  custom_date: 1574769933368,
  custom_date1: new Date("2019-10-14T11:15:53.296Z"),
})

The lookup field passed in the Hubspot property name to be used as lookup field dashboard setting must also be passed in the traits object of the identify call containing the lookup value.

A sample snippet is shown below:

rudderanalytics.identify({
  name: "Alex Keener",
  phone: "+1-202-555-0146",
  traits: {
    "lookupField": "alex@example.com",
  },
})

If you pass a lookup field in the dashboard setting but not under the identify call’s traits, RudderStack will take email as the default lookup field.

Track

A track call lets you record various user actions and any properties associated with them.

To associate a track call with a user, you need to specify the user’s email under context.traits.

RudderStack associates the track events with the same user only after you make a successful identify call. However, if you send a track call without making any identify call first and there is no contact present in HubSpot, RudderStack will not associate the events as there is no identifier.

A sample track event is as shown:

rudderanalytics.track(
  "Order Completed", {
    value: 30,
  }, {
    context: {
      traits: {
        firstname: "Alex",
        city: "New Orleans",
        country: "USA",
        phone: "+1-202-555-0146",
        email: "alex@example.com",
      },
    },
  }
)

Property mappings

The following table lists the properties and their mappings between RudderStack and HubSpot for the track call:

You must send either of the utk, email, or objectId (can be contact_id or visitor_ id) properties to make a track call successfully.

Custom behavioral events

The custom behavorial events can be used for both the authentication types. However, they must have the analytics.behavioral_events.send permission to be used for private apps.

Custom behavioral events are account-defined events in HubSpot that store event details in the event properties. You can create custom behavioral events and their associated properties in the RudderStack dashboard as explained in the New API section.

The following parameters are sent in the custom behavorial events:

• Identifier: Either the contact ID, email, or utk (user token) of the contact associated with the event. The utk is the user token stored in the visitor’s hubspotutk browser cookie.
• Event name: The internal name of the event which can be found in HubSpot.
• Properties object: When you create a custom behavioral event in HubSpot, some default properties are provided with those events, explained in the below section.

Property mappings

The following table lists the optional and default property mappings between RudderStack and HubSpot for custom behavioral events:

Questions? Contact us by email or on Slack