HubSpot Destination

HubSpot is an inbound marketing and sales platform that helps companies attract visitors, convert leads, and close customers. The analytics.js HubSpot Destination is open-source. You can browse the code on GitHub.

This document was last updated on March 30, 2018. If you notice any gaps, outdated information or simply want to leave some feedback to help us improve our documentation, let us know!

Getting Started

Before you start, make sure HubSpot supports the source type and connection mode you’ve chosen to implement. You can learn more about connection modes here.

Web Mobile Server
📱 Device-mode
☁️ Cloud-mode
  1. From your Segment UI’s Destinations page click on “Add Destination”.
  2. Search for “HubSpot” within the Destinations Catalog and confirm the Source you’d like to connect to.
  3. If you haven’t already done so, add your API Key from HubSpot and drop into the “API Key” field within the Segment UI.
  4. Navigate to the “Settings” page within the HubSpot UI to find your Hub ID and drop into the “Hub ID” field within the Segment UI.
  5. When you activate the destination, our CDN will be updated in about 45 minutes and the HubSpot snippet will be initilized and begin recording data.


If you’re not familiar with the Segment Specs, take a look to understand what the Page method does. An example call would look like:

IMPORTANT: An initial page call is required for data to be sent to HubSpot using Analytics.js. This is included by default in your Segment snippet.


If you’re not familiar with the Segment Specs, take a look to understand what the Identify method does. An example call would look like:

analytics.identify('user1234', {
  email: '',
  firstname: 'Peter',
  lastname: 'Gibbon'

IMPORTANT: HubSpot’s device-mode integration has two conditions for identify to successfully create or update a contact. A value must be included and either a page or track call must be called. You can read more from HubSpot’s documentation here. If you are using HubSpot’s cloud-mode integration, an identify call will update records without a page or track call being needed.

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.

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.

If you specify a company name (via, it will show up as a property of the contact (you can find it in HubSpot’s UI using About [contact] > View > View All Properties), but it will not show up as the user’s company under [contact]’s Company.

The following traits are tagged as special fields within HubSpot:

- address
- city
- companyName
- email
- firstName
- lastName
- position
- phone
- zip


If you’re not familiar with the Segment Specs, take a look to understand what the Track method does. An example call would look like:

analytics.track("Clicked Buy Now button", {
  value: 20.5

IMPORTANT: You must have a HubSpot Enterprise account for traits from an identify call to be passed through to your track call and be successfully sent as a custom event to HubSpot.

The event will appear in your HubSpot UI but may take up to 60 minutes to appear in the graph visualization.


When calling from any of our server-side sources you must provide the contact’s email as so that HubSpot can tie the event to the appropriate contact. An example call in Python would look like:

  event='Bought Item',
    'email' : '',

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 send traits using 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:

  event='Bought Item',
    'email': '',
    'traits': {
    'firstname': 'Peter',
    'lastname': 'Gibbons'


NOTE: Group calls are not compatible with our Analytics.js library.

If you’re not familiar with the Segment Specs, take a look to understand what the Group method does. An example call would look like:{
  groupId: "some_group_id",
  userId: "some_user_id",
  traits: {
    website: "",
    name: "Example Inc."

Group calls map to the HubSpot Companies API. Segment’s integration is responsible for creating and updating company objects with whatever traits you set, as well as associating individual contacts to a company.

IMPORTANT: There are three requirements to creating companies and associating contacts:

  1. Group calls only take effect when called using server-side libraries or mobile libraries, not using our client-side javascript library.
  2. Your contact must have been identified and created within HubSpot (called using analytics.identify for this userId first).
  3. You must include a website trait in your group call, and it must be a full, valid, and complete URL. HubSpot uses the domain of the website trait as a unique identifier for companies. To create a new company you must use the full URL and not just the subdomain.

The following group traits are supported as special properties within HubSpot:

- address
- city
- state
- zip
- country
- description
- employees
- industry
- phone
- website


API Call Limits

HubSpot limits the total amount of hourly and daily requests we can make to their API on your behalf. Read more about these limits here.

HubSpot Plan: Free & Starter

  • Maximum Number of API Calls per 10 Seconds, per Key or Token: 100
  • Maximum Number of API Calls per Day, per Key or Token: 250,000

HubSpot Plan: Professional and Enterprise

  • Maximum Number of API Calls per 10 Seconds, per Key or Token: 100
  • Maximum Number of API Calls per Day, per Key or Token: 500,000

HubSpot Plan: API Add-On (Any Tier)

  • Maximum Number of API Calls per 10 Seconds, per Key or Token: 120
  • Maximum Number of API Calls per Day, per Key or Token: 1,000,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, 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!

Invalid ‘lifecyclestage’

When using any of our server-side sources, our connector will infer traits.lifecycle_stage as lifecyclestage. If you’re using a custom contact property for custom lifecycle stage’s, you should give the property a distinct name, such as custom_lifecycle_stage.

Loading Forms SDK

Segment gives you the option to load the HubSpot Forms SDK alongside their tracking library. This can be done by enabling the Load Forms SDK setting when configuring your HubSpot integration.

Note: The Forms SDK expects to be loaded synchronously but analytics.js is loaded asynchronously. Therefore, in order to interact with the API, you need to run your code inside an analytics.ready callback. Here’s an example:

    portalId: '',
    formId: '',
    css: '',
    cssRequired: ''


You can send computed traits and audiences generated using Segment Personas to this destination as a user property. To learn more about Personas, contact us for a demo.

For user-property destinations, an identify call is sent to the destination for each user being added and removed. The property name is the snake_cased version of the audience name, with a true/false value to indicade membership. For example, when a user first completes an order in the last 30 days, Personas sends an Identify call with the property order_completed_last_30days: true. When the user no longer satisfies this condition (for example, it’s been more than 30 days since their last order), Personas sets that value to false.

When you first create an audience, Personas sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync.


Segment lets you change these destination settings from the Segment app without having to touch any code.


You can request your API Key from HubSpot. Please follow the help center article. 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.

Load Forms SDK

Select this option if you would like Segment to automatically load the Hubspot Forms SDK onto your site. This will offload the manual work required to add the embed code to your site’s header.

Important: The Forms API expects that the script is loaded onto your page synchronously but analytics.js is loaded asynchronously. To prevent errors, please ensure you are interacting with the Forms API inside an analytics.ready callback.

This page was last modified: 05 Aug 2020

Get started with Segment

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