HubSpot Destination

Segment makes it easy to send your data to HubSpot (and lots of other destinations). Once you've tracked your data through our open source libraries we'll translate and route your data to HubSpot in the format they understand. Learn more about how to use HubSpot with Segment.

Getting Started

When you toggle on HubSpot in Segment, this is what happens:

  • Our CDN is updated within 5-10 minutes. Then our snippet will start asynchronously loading hubspot.js onto your page. This means you should remove HubSpot’s snippet from your page.
  • HubSpot will automatically start recording data.

Page

When sending data to Hubspot via analytics.js, an initial page call is required. By default, this is already added in your Segment snippet. Server-side page calls coming soon!

Identify

When you call identify on analytics.js, we’ll store contact information with the traits you provide. The userId is ignored since HubSpot does not use a userId. However, you must include an email trait as the userId or as traits.email.

Hubspot doesn’t accept plain identity information - traits are attached to and passed along with your next Segment page or track event. Traits also won’t persist across pages given how Hubspot’s Javascript is structured, so if you call identify, you must call page or track at least once on the same page in order to flush your data to Hubspot. Here’s more background in Hubspot’s documentation.

Any traits that aren’t contact fields in HubSpot will be removed from the request. To find out which fields you can set, check out the custom field names in Contacts > Contact Settings. Example field names are “firstname”, “lastname”, “company”, “phone”, etc. Note: We automatically convert ‘firstName’ and ‘lastName’ to ‘firstname’ and ‘lastname’ to match HubSpot’s field format. These are the only converted property names for this destination.

Important: Hubspot does not accept any trait keys that contain uppercases or spaces. So for any custom traits you send we will lowercase them and replace any spaces with an underscore.

Track

When you call track we’ll send a custom event to HubSpot.

Note: HubSpot custom events are available to HubSpot Enterprise customers only.

Server Side

When you call track from any of our server-side sources, we’ll send the custom event to Hubspot. Because HubSpot needs to know which contact you want to tie this event to, you must provide the contact’s email as properties.email in every track call you want to send to HubSpot.

Here’s a python example:

analytics.track(user_id='YOUR_USER_ID', event='Bought Item', properties={
    'email' : 'peter@initech.com',
})

In this case, your HubSpot eventId is ‘Bought Item’. If you want to use an existing eventId, you can use it instead of the event value (ie. Bought Item). If you don’t want to match an existing eventId, you can use any event label and HubSpot will auto-create the event for you.

Setting Contact Properties on Track

Although we recommend you to send traits via identify, you can also set HubSpot properties on a track call, as allowed by their events API. You might want to use this method if you’re running out of API calls on the identify requests.

Include HubSpot contact properties into the context.traits object:

analytics.track(user_id='YOUR_USER_ID', event='Bought Item', properties={
    'email': 'peter@initech.com',
}, context={
    'traits': {
        'firstname': 'Peter',
        'lastname': 'Gibbons'
    }
})

Troubleshooting

API Call Limits

HubSpot limits the total amount of hourly and monthly requests we can make to their API on your behalf. Check out these limits.

Maximum Number of API Calls per Second, per Key or Token: 10

Maximum Number of API Calls per Day, per Key or Token: 40,000

Sending Dates as Property Values

HubSpot’s API has specific requirements regarding how dates should be formatted before they are delivered as contact properties with date types.

In order to ensure proper transformation of these properties, please pass them to Segment as ISO-8601 formatted strings and not as UNIX timestamps. Here’s a Javascript example:

analytics.identify('userid', {
    offerDate: new Date() // not Date.now()!
});

Supported Sources and Connection Modes

WebMobileServer
📱 Device-based
☁️ Cloud-based

To learn more about about Connection Modes and what dictates which we support, see here.

Settings

Segment lets you change these destination settings via your Segment dashboard without having to touch any code.

API Key

You can request your API Key from HubSpot by filling out their API Key request form at app.hubspot.com/keys/get. Don’t use the temporary authorization code from Settings > API Access! It should look something like this: dfdbfe6f-e7bf-4938-8e82-7d1938e48ab8

Hub ID

You can find your Hub ID on the Settings page of your HubSpot account. It should be a series of numbers, like 997086.


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!