Hubspot Object | Captured in Hull as | Description |
---|---|---|
contact Contact | User | Most standard Hubspot fields are captured by default, Additional fields configurable in Connector Settings |
company Company | Account | Most standard Hubspot fields are captured by default, Additional fields configurable in Connector Settings |
Email Sent Event | User Event | The message was sent to and received by our delivery provider, which has queued it for further handling. |
Email Dropped Event | User Event | The message was rejected, either by HubSpot or by our delivery provider, and no attempt will be made to deliver the message. |
Email Processed Event | User Event | The message has been received by our delivery provider, which has indicated it will attempt to deliver the message to the recipient's email server. |
Email Delivered Event | User Event | The recipient's email server has accepted the message and the message has been successfully delivered to the recipient. |
Email Deferred Event | User Event | The recipient’s email server has temporarily rejected message, and subsequent attempts will be made to deliver the message. |
Email Bounced Event | User Event | The recipient's email server could not or would not accept the message, and no further attempts will be made to deliver the message. |
Email Opened Event | User Event | The recipient opened the message |
Email Clicked Event | User Event | The recipient clicked on a link within the message |
Status Changed Event | User Event | The recipient changed her email subscriptions in some way |
Spam Report Event | User Event | The recipient flagged the message as spam. |
Hull Object | Sent to Hubspot as | Description |
---|---|---|
User | Contact Contact | Select the segments of Users you want to sync as Contacts in Hubspot. A User that does not belong to one of these segments will not be sent to Hubspot |
Account | Company Company | Select the segments of Accounts you want to sync as Companies in Hubspot. An Account that does not belong to one of these segments will not be sent to Hubspot. |
Hull’s HubSpot integration enables syncing of HubSpot Contacts & Companies with all your other tools through Hull’s Customer Data Platform. Teams use Hull with HubSpot for:
If you have questions, feedback, or spot any outdated information, we’d love to hear from you via email.
To install the HubSpot integration, you must have a HubSpot admin permissions to add and authenticate third party apps.
Hull can sync the following objects to HubSpot. New data is upserted in both directions - existing profiles are updated, else new profiles are created automatically.
Data Object | Hull | HubSpot |
---|---|---|
Person | User | Contact |
Company | Account | Company |
Note: HubSpot Companies are not handled by default. You must configure this.
In the HubSpot Connector Dashboard, click the Settings tab. Here you can set the rules to map, filter & link incoming & outgoing data.
There are four sections of settings:
HubSpot Contacts and their updates are fetched into Hull manually or on a schedule.
When new data about a HubSpot Contact is ingested, Hull follows this process:
email
HubSpot Contact VID
is captured as an anonymous_id
and hubspot/id
in Hull User profiles.
Note: If more than one Hull User exists with the same
VID
and without a unique external_id then they will be merged. AUser merged
event will show the before/after difference in attribute values. Learn more about User merging
HubSpot Companies are not handled by default. This must be enabled in the Connector Settings under the Fetch accounts toggle.
You must select what account-level identifier to map into. This is domain
by default.
HubSpot Companies and their updates are fetched automatically on a schedule. This can be also be fetched manually in the Credentials & Actions tab.
When new data about a HubSpot Company is ingested, Hull follows this process:
domain
for default). Skip if not.domain
)HubSpot Company ID
is captured as an anonymous_id
in Hull Account profiles.
Note: If more than one Hull Account exists with the same
domain
and without a unique external_id then they will be merged. Learn more about Account merging.
Hull will associate Users and Accounts by a common domain
. e.g. romain@hull.io
and www.hull.io
will be associated.
If you’d also like to match Users and Accounts in Hull by the Contact-Company relationships you have in HubSpot, you can configure this in the Connector Settings under the Link users in Hull toggle.
Hull will link Users with Accounts if:
If the HubSpot Company does not have a required identifier, the User will be associated with an empty Hull Account.
When a HubSpot Contact or Company is deleted in HubSpot, you will have the option to mark the associated Hull User or Hull Account as deleted in Hull. This action will remove the hubspot id from the associated entity in Hull and the field “hubspot/deleted_at” will be added with the timestamp of the deletion.
By default, Hull will not send out Hull Users or Hull Accounts to HubSpot that have the field “hubspot/deleted_at” set. If you would like to send those entities back out to HubSpot, which will create a new HubSpot Contact or Company, you may turn off the toggles “Ignore Deleted Contacts” and/or “Ignore Deleted Companies”.
Hull Users must be in a whitelisted User Segment to be synced to HubSpot. By default, no Users are synced.
When Hull publishes a User Update for a User whitelisted to sync to HubSpot:
email
. Skip if not.email
exists, sync User Update to HubSpot.email
or hubspot/id
(Contact VID
in HubSpot)Hull Accounts must be in a whitelisted Account Segment to be synced to HubSpot. By default, no Accounts are synced.
When Hull publishes an Account Update for an Account whitelisted to sync to HubSpot
domain
. Skip if not.domain
exists, sync Account Update to HubSpotdomain
You can associate HubSpot Contacts and Companies based on logic you have in Hull. Click the Link Contacts in HubSpot toggle in the Connector Settings.
Hull will link Contacts & Companies in HubSpot if:
HubSpot Marketing Emails will be imported into Hull manually or on a schedule. Users have the option to fetch all email events created in the last 24 hours or fetch all email events in their HubSpot instance. Email events can also be fetched by Hull on a 5 minute schedule by turning on the toggle “Fetch Email Events”. The fetch buttons will fetch email events whether or not this toggle is on or off.
For an email event to be successfully fetched by Hull, the email must be a part of a marketing email campaign.
Hull will only retrieve the email events that the user has selected. The available events to retrieve are:
Email Sent |
Email Dropped |
Email Processed |
Email Delivered |
Email Deferred |
Email Bounced |
Email Opened |
Email Link Clicked |
Unsubscribed / Subscribed |
Email Marked as Spam |
Hull will retrieve the following fields from a marketing email:
Email Campaign Id |
Portal Id |
Email Id |
Link Url |
Sent By |
Recipient |
Created At |
Email Subject |
Email Body |
The email body will only be retrieved if it is a plaintext html body.
When using HubSpot pages or HubSpot tracking code, every website visitor is assigned a unique Visitor ID called UTK. When and anonymous visitor fills out a form HubSpot will automatically associate their previous page views with a newly created or existing Hubspot Contact.
This connector allows to resolve HubSpot UTK tracked by Website connector into Contact ID to achieve the same results, this is how the feature works:
hubspot-utk:xxx
anonymous_id
which is the Visitor UTK IDhubspot:xxx
anonymous_id
which is the Contact IDhubspot:xxx
anonymous_id
As a result the anonymous Hull User will have both UTK ID and Contact ID stored in the anonymous_ids. This will allow to merge this Hull User with all page view events (and other events) with Hull Users tied to HubSpot Contact with HubSpot attributes. This will happen as soon as HubSpot Contact is fetched by the connector.
IMPORTANT: HubSpot does not create actual Contact before Visitor takes a specific action on the website. As a result even if the UTK resolution is run by the connector and both IDs are set as anonymou_ids
the merge can’t happen.
Here is how the connector can be configured:
Resolve Contact ID from Visitor UTK - this is a global toggle that enables the feature for manual replays and ongoing traffic
Visitor Segment Filter - this is a list of segments of Users which will be automatically resolved
See our documentation for a step-by-step guide how to enable the whole flow using HubSpot and Website Connectors.
Filter which Users & Accounts are synced to HubSpot with User & Account Segments in the Connector Settings.
Map which User & Account attributes are synced to and from HubSpot with the field mappers in the Connector Settings.
Quoted from Hull’s documentation: “`text Supported Attribute values include:
Dates -> HubSpot documentation text Date properties will only store the date, and must be set to midnight UTC for the date you want. For example, May 1 2015 would be 1430438400000 (01 May 2015 00:00:00 UTC).
Hull stores dates using hours, minutes, and seconds. The connector will convert a date to the appropriate format that HubSpot expects by removing the hours, minutes, seconds of the related date. As a result, if you send a Hull Date such as 15 June 2019 10:05:22 UTC, a HubSpot Date field will receive it as 15 June 2019 00:00:00 UTC. This limitation comes from HubSpot itself, since you only use the day, month and year when you pick a date on the Dashboard. See the example below.
text Datetime properties can store any time, so any valid millisecond timestamp would be accepted. In HubSpot, datetime properties are displayed based on the time zone of the user viewing the record, so the value will be converted to the local time zone of the user.
Here the HubSpot’s Datetime
format is exactly the same as Hull’s Date
format.Enumeration (made of above types), mostly used as a “choose your value(s)” from a dropdown list. In this data type, you can end up having an array of the selected type. Such a thing is happening for the Hull segments
field that you can notice in any HubSpot contact imported from Hull.
📚 Other links used for that documentation - Contact Properties Overview - Company Properties Overview
Here you will find what type conversions are supported in the table below. - ✅ : Works and is intuitive to convert - ⚠️ : Can work but under certain condition(s) - ❌ : Cannot be converted or would not make sense to
Hull Type | HubSpot String | HubSpot Number | HubSpot Bool | HubSpot Date | HubSpot Datetime | HubSpot Enumeration |
---|---|---|---|---|---|---|
String | ✅ | ✅ | ⚠️¹ | ❌ | ❌ | ❌ |
String_Array | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
Numeric | ✅ | ✅ | ⚠️² | ❌ | ❌ | ❌ |
Boolean | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
Date | ✅ | ✅ | ❌ | ⚠️³ | ✅ | ❌ |
JSON | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
HubSpot type | Hull String | Hull Array of strings | Hull Boolean | Hull Date | Hull JSON |
---|---|---|---|---|---|
String | ✅ | ❌ | ⚠️¹ | ✅ | ❌ |
Number | ✅ | ❌ | ⚠️² | ❌ | ❌ |
Bool | ✅ | ❌ | ✅ | ❌ | ❌ |
Date | ✅ | ❌ | ❌ | ✅ | ❌ |
Datetime | ✅ | ❌ | ❌ | ️✅ | ❌ |
Enumeration | ❌ | ✅ | ❌ | ❌ | ❌ |
A HubSpot “Picklist” is a HubSpot field with a customizable format. Most of the time, you will encounter them under the format of a dropdown field with a list of checkboxes. To reach that result, picklists have in their definitions the enumeration
HubSpot "type"
, and the checkbox
HubSpot "fieldType"
. More information can be found in HubSpot’s API documentation
Here is what would be the definition of an Enumeration
using that dropdown of checkboxes: json { "name": "hull_test_enum", "label": "Test Enumeration", "groupName": "hull", "type": "enumeration", "fieldType": "checkbox", "options": [ { "label": 1, "value": 1 }, { "label": "Option 2", "value": 2 }, { "label": 333, "value": "3" }, { "label": "Big Number", "value": 1565354818310 } ] }
You can customize the name of each element in the "options"
by changing the "label"
, however the "value"
holds the true content for each option.
This enum results in the following HubSpot UI element:
All the selected options in that field will be stored in the contact properties using the following format: json { "value": "1;3;1565354818310" }
Again, note here that the selected options are referred with the "value"
fields defined above, not as their "label"
.
The Hull - string array <=> HubSpot - Enum conversion works in both directions, by parsing each values separated by a ;
for incoming data.
In the case of outgoing data, for each element in the Hull - string array, "value"
and "label"
fields will share the same value when creating the definition of the HubSpot enumeration. You will not be able to customise the label if you export a Hull - string array to HubSpot.
Data type | Hull | HubSpot |
---|---|---|
Standard Person Attributes | User Attributes | Contact Properties |
Custom Person Attributes | User Attributes | Custom Contact Properties (grouped under Hull ) |
Standard Company Attributes | Account Attributes | Company Properties |
Custom Company Attributes | Account Attributes | Custom Company Properties (grouped under Hull ) |
All default HubSpot Contact & Company Properties are fetched and stored as a HubSpot attributes group on Hull User & Account profiles.
In the Connector Settings, under the Custom Fields Sync (HubSpot to Hull) headings for Users & Accounts, you can map and name HubSpot Custom Properties into Hull. These will also appear under the HubSpot attributes group on Hull User & Account profiles.
In the connector settings, under the Custom Fields Sync (Hull to HubSpot) headings for Users & Accounts, you can map Hull User & Account Attributes to Custom Properties in HubSpot Contact & Company profiles. These will appear under a Hull group in HubSpot.
You can create new properties in HubSpot from Hull field mapping. As you type right column of the field mapper, you’ll be prompted to “Create” the field you’re typing.
You can sync Hull User & Account Segments to HubSpot.
Group | Hull | HubSpot |
---|---|---|
Groups of people | User Segments | Hull_Segments contact property |
Groups of companies | Account Segments | Hull_Segments company property |
Hull ingests data from the HubSpot connector through the Firehose API.
Learn more about HubSpot’s API usage guidelines.
HubSpot API limits | 40,000 per day |
---|---|
HubSpot Rate Limits | 10 requests per second |
Bulk operation limitations | Batches of 100 contacts/customers |
Fetch updates sync frequency | Every 5 minutes |
Sync data from Hull to HubSpot | With every User or Account update |
Check you have setup identifiers for accounts. See data mapping
Check your connector logs for any incoming.job.error
. If you see any with Permission error
, you need to re-authenticate the HubSpot Connector. Go to the Credentials & Actions and perform the OAuth flow authorization again using the Start over button.
All your connector settings (including data mapping) will remain the same.
After re-authenticating, your data flow should resume. You can also run a Fetch all Contacts or Fetch all Companies in the connectors tab. Search the connector logs for incoming.user.success
or incoming.account.success
to verify data is flowing again - this can take up to 5 minutes.
Note: Make sure you link with the same HubSpot portal. Changing the portal can lead to data corruption.
In the HubSpot Connector settings, go to Credentials & Actions and then click Fetch all Contacts for contact properties or Fetch all Companies for company properties.
It may take a few minutes for the import of data to be ingested and be shown in Hull.
You can manually sync the Users and Accounts to HubSpot. Go to the User or Account Profiles, or create a User or Account Segment then select the Send to button and choose HubSpot. Click confirm.
Make sure you set the required account identifiers in the Connector settings.
If you see duplicate property value
error in your outgoing.user.error
or outgoing.account.error
logs it means that you have duplicate entry in your outgoing attribute mapping.
You can inspect hubspotWriteContact
parameter in the logs to see the exact payload the connector tried & failed to send to HubSpot. Search for any attribute name which appears twice in the same payload. Once you have identified the duplicate attribute, remove the extra entry in the attributes mapper in the Connector Settings.
Once you have reconfigured you data mapping, resend the affected Users & Accounts to HubSpot with the Send to button on the Profiles or Segmentation tool.
If you have any questions or have suggestions to improve this documentation, please email us.
Learn how Hull unifies and syncs customer data by watching our product tour