HubSpot Source

HubSpot is an all-in-one marketing tool that helps attract new leads and convert them into paying customers, with features like landing page creation and email automation.

Hubspot is an Object Cloud Source which can export data from its third party tool and import it directly into your Segment warehouse.

Are you trying to setup HubSpot as a destination to receive data from Segment? Go here HubSpot Destination.

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

Getting Started

  1. From your workspace’s /sources page, click add source.

  2. Choose HubSpot.

  3. Give the source a nickname and a schema name. The nickname will be used to designate the source in the Segment interface, and the schema name is the namespace you’ll be querying against in your warehouse. Both can be whatever you like, but we recommend sticking to something that reflects the source itself, like HubSpot for nickname and hubspot, hub, or hubspot_prod for the schema name.

    Note that you can add multiple instances if you have multiple HubSpot accounts. That’s why we allow you to customize the source’s nickname and schema name!

  4. Finally, connect an account with admin API permissions to access your HubSpot data. This account should be an active user on a Professional or Enterprise plan. Check out HubSpot’s docs on how to get your API Key.

Voila! We’ll begin syncing your HubSpot data into Segment momentarily, and it will be written to your warehouse at your next Warehouse run.

Components

Sync

The HubSpot source is built with a sync component, which means we’ll make requests to their API on your behalf on a 3 hour interval to pull the latest data into Segment. In the initial sync, we’ll grab all the HubSpot objects (and their corresponding properties) according to the Collections Table below. The objects will be written into a separate schema, corresponding to the source instance’s schema name you designated upon creation (ie. my_source.charges).

Our sync component uses an upsert API, so the data in your warehouse loaded via sync will reflect the latest state of the corresponding resource in HubSpot. For example, if ticket_status goes from open to closed between syncs, on its next sync that tickets status will be closed.

The source syncs and warehouse syncs are independent processes. Source runs pull your data into the Segment Hub, and warehouse runs flush that data to your warehouse. Sources will sync with Segment every 3 hours. Depending on your Warehouses plan, we will push the Source data to your warehouse on the interval associated with your billing plan.

Collections

Collections are the groupings of resources we pull from your source. In your warehouse, each collection gets its own table.

Event History

Due to HubSpot’s API Rate Limits, by default, the HubSpot source only syncs the past month of data for email_events and email_subscription_event_changes.

CollectionTypeDescription
contactsObjectContacts represent people in an Organization’s address book. For more info, check out HubSpot’s API docs
contact_identity_profilesObjectContact identity profiles represent identities of a contact.
contact_identitiesObjectContact identities represent communication methods for a contact’s profile (email, lead, etc.).
form_submissionsEventForm submissions represent input from contacts in forms created via HubSpot
dealsObjectDeals for HubSpot CRM.
contact_listsObjectContact lists are lists of contacts in an Organization’s address book. For more info, check out HubSpot’s API docs about the resource
companiesObjectCompanies visible to the portal in the HubSpot CRM. For more info, check out HubSpot’s API docs about the resource
email_campaignsObjectEmail campaigns for marketing automation. For more info, check out HubSpot’s API docs about the resource
email_eventsEventEmail events based on user actions. For more info, check out HubSpot’s API docs about the resource
email_subscriptionsObjectEmail subscriptions of campaign contacts.
email_subscription_event_changesEventEmail subscription event changes represent changes to a recipient’s subscription that came about as a result of an email event

Collection Properties

Below are tables outlining the properties included in the collections listed above. To see the full description of each property, please refer to the Google Adwords documentation linked in each collection above.

Contacts

Property NameDescription
added_atThis is a timestamp for when the email address was added.
canonical_vidvid of the primary contact (record that was merged into).
emailcontact’s email.
form_submissionsA list of form submissions for the contact. This list will be empty for records with no form submissions.
is_contactIndicates if the record is a valid contact record. Any record where this is set to false is not a valid contact. Those records will only have placeholder data and cannot be updated.
lead_guidLEAD_GUID identities are an internal reference and should not be used.
list_membershipA list of objects representing the contact’s membership in contact lists. This list may be empty if the record is not a member of any lists.
merged_vidsvid of the primary contact (record that was merged into).
portal_idThe Portal ID (Hub ID) that the record belongs to.
profile_tokenA unique token that can be used to view the contact without logging into HubSpot. See the profile-url below.
profile_urlA URL that can be used to view the contact data without logging in. Anyone with this link would be able to view (but not edit) the record. Note: You can force a login for the public link by changing the Public View Login option in your Contact Settings.
properties_company_valueThe current value of the company property.
properties_firstname_valueThe current value of the firstname property.
properties_lastmodifieddate_valueThis timestamp is of the time the property was last set.
properties_lastname_valueThe current value of lastname the property.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.

Contact Identity Profiles

Property NameDescription
contact_idThe original id for this identity.
deleted_changed_timestampDEPRECATED - This field is no longer used
identitiesA list of the individual identies for this pointer
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.
saved_at_timestampA timestamp of when the identity was last updated.

Contact Identities

Property NameDescription
contact_idThe original id for this identity.
is_primaryIndicates if this is a primary contact.
is_secondaryIndicates if this is a secondary contact.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.
timestampA timestamp for when the identity was created.
typeThe type of the identity.

Form Submissions

Property NameDescription
form_idThe Hub ID that the form belongs to.
form_typeThis fields is deprecated and will always be HUBSPOT
page_idThe id of the page.
page_titleThe title of the page.
page_urlThe URL of the page.
portal_idThe Hub ID that the form belongs to.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.
timestampA timestamp of the time the current value was set.
titleThe title of the form.

Deals

Property NameDescription
amountThe amount of the deal.
associated_company_idsA list of integers, each one represents the companyId of a company record. Deals can only be associated with a single company, so there will only be up to one item in the list.
associated_vidsA list of integers, each one will be the vid of a contact record.
dealnameThe internal name of the property
dealstageThe stage of the deal.
hs_*(Specific to user)
hubspot_*(Specific to user)
is_deletedWhether or not the record is deleted.
notes_*(Specific to user)
num_*(Specific to user)
pipelineThe type of pipeline for this deal.
portal_idThe Portal ID (Hub ID) that the record belongs to.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.
vidThe vid of the contact record.

Contact Lists

Property NameDescription
archivedWhether or not the list is archived.
author_idThe id of the author.
created_atA timestamp for the time this contact list was created.
deleteableIf this is false, this is a system list and cannot be deleted. This value may not be present for all lists. In those cases, this value may be treated as true (the list may be deleted). When this value is true, you may still get an error deleting the list if it’s in use by other lists or workflows.
dynamicTrue if the list is a dynamic (smart) list, false if static.
filters_0_0_filter_familyThis is a list of filters used to determine list membership. This field may be an empty list, for lists with no criteria.
internal_list_idDEPRECATED, this is an internal field and should not be used. Use the ‘listId’ to reference the list.
list_typeDEPRECATED, use the ‘dynamic’ field to determine if the list is dynamic or static.
meta_data_last_processing_state_change_atA timestamp of the last time that the processing state changed.
meta_data_last_size_change_atA timestamp of the last time that the size ofthe list changed. A value of 0 indicates that the list hasn’t changed size since its creation.
meta_data_processingThe number of contacts in the list.
meta_data_sizeDONE indicates the list has finished processing, any other value indicates that list membership is being evaluated.
nameThe name of the list.
portal_idThe Hud ID that the list belongs to.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.
updated_atA timestamp of the time that the list was last modified.

Companies

Property NameDescription
countryThe internal name of the property.
createdateA timestamp for when the record was created.
first_contact_createdateA timestamp for when the first contact was created.
hs_*(Specific to user)
is_deletedWhether or not the record is deleted.
nameThe internal name of the property
num_associated_contactsThe number of associated contacts.
portal_idThe Hub ID that the company belongs to.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.

Email Campaigns

Property NameDescription
app_idAn ID referencing the app.
app_nameThe name of the app.
content_idAn ID referencing the content.
counters_*(Specific to user)
nameThe name of the campaign.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.
subjectThe email subject line for this campaign.
typeThe type of email campaign.

Email Subscriptions

Property NameDescription
bouncedA HubSpot employee explicitly initiated the status change to block messages to the recipient. (Note this usage has been deprecated in favor of dropping messages with a ‘dropReason’ of BLOCKED_ADDRESS.)
emailThe email address of the subscriber.
marked_as_spamWhether or not the email is marked as spam.
portal_idAn ID referencing the HubSpot Portal which is associated with the item. This will correspond to your portal.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.
statusThe status of the subscription. (subscribed or unsubscribed)
subscribedWhether or not the status is subscribed.
unsubscribe_from_portalWhether or not the status is unsubscribed from portal.

Email Subscription Event Changes

Property NameDescription
caused_by_event_createdA timestamp for when the event was created.
caused_by_event_idThe EventId which uniquely identifies the event which directly caused this event. If not applicable, this property is omitted.
changeThe change which occurred. This enumeration is specific to the ‘changeType’.
change_typeThe type of change which occurred.
email_subscription_event_idAn ID referencing the email subscription which is associated with the change.
portal_idAn ID referencing the HubSpot Portal which is associated with the change. This will correspond to your portal.
received_atThis timestamp is added to incoming messages as soon as they hit Segment API.
sourceThe source of the subscription change.
timestampA timestamp for when this change occurred. If ‘causedByEvent’ is present, this will be absent.

Adding Destinations

Currently, Warehouses are the only supported destination for object-cloud sources.


If you have any questions, or see anywhere we can improve our documentation, please let us know!