This integration is powered by Singer's HubSpot tap and certified by Stitch. Check out and contribute to the repo on GitHub.
For support, contact Stitch support.
HubSpot integration summary
Stitch’s HubSpot integration replicates data using the HubSpot REST API. Refer to the Schema section for a list of objects available for replication.
HubSpot feature snapshot
A high-level look at Stitch's HubSpot (v2.0) integration, including release status, useful links, and the features supported in Stitch.
STITCH | |||
Release Status |
Released |
Supported By | |
Stitch Plan |
Paid |
Singer GitHub Repository | |
DATA SELECTION | |||
Table Selection |
Supported |
Column Selection |
Supported |
REPLICATION SETTINGS | |||
Anchor Scheduling |
Supported |
Advanced Scheduling |
Unsupported |
Table-level Reset |
Unsupported |
Configurable Replication Methods |
Unsupported |
TRANSPARENCY | |||
Extraction Logs |
Supported |
Loading Reports |
Supported |
Connecting HubSpot
HubSpot setup requirements
To set up HubSpot in Stitch, you need:
- A paid Stitch plan. While those currently in the Free Trial will also be able to set up HubSpot, replication will be paused until a paid plan is selected after the trial ends.
-
For HubSpot CRM or Marketing products: Administrator permissions in HubSpot. Note: To replicate email events, you’ll need to have Super Admin permissions in HubSpot.
-
For the HubSpot Sales product: Sales Administrator permissions in HubSpot.
More information about HubSpot user roles and permissions can be found in HubSpot’s documentation.
Step 1: Add HubSpot as a Stitch data source
- Sign into your Stitch account.
-
On the Stitch Dashboard page, click the Add Integration button.
-
Click the HubSpot icon.
-
Enter a name for the integration. This is the name that will display on the Stitch Dashboard for the integration; it’ll also be used to create the schema in your destination.
For example, the name “Stitch HubSpot” would create a schema called
stitch_hubspot
in the destination. Note: Schema names cannot be changed after you save the integration.
Step 2: Define the historical sync
The Sync Historical Data setting will define the starting date for your HubSpot integration. This means that:
- For tables using Incremental Replication, data equal to or newer than this date will be replicated to your data warehouse.
- For tables using Full Table Replication, all data - including records that are older, equal to, or newer than this date - will be replicated to your data warehouse.
Change this setting if you want to replicate data beyond HubSpot’s default setting of 30 days. For a detailed look at historical replication jobs, check out the Syncing Historical SaaS Data guide.
Step 3: Create a replication schedule
In the Replication Frequency section, you’ll create the integration’s replication schedule. An integration’s replication schedule determines how often Stitch runs a replication job, and the time that job begins.
HubSpot integrations support the following replication scheduling methods:
To keep your row usage low, consider setting the integration to replicate less frequently. See the Understanding and Reducing Your Row Usage guide for tips on reducing your usage.
Step 4: Authorize Stitch to access HubSpot
- Next, you’ll be prompted to sign into your HubSpot account.
-
After you log into HubSpot, a screen with a list of your HubSpot accounts will display. Click the account you want to connect to Stitch.
Note that Stitch will only ever read your data. Stitch will never modify or delete any data in your HubSpot account.
- After the authorization process is successfully completed, you’ll be directed back to Stitch.
- Click All Done.
Step 5: Set tables and columns to replicate
To complete the setup, you’ll need to select the tables and columns you want to replicate to your data warehouse.
Check out the Schema section to learn more about the available tables in HubSpot and how they replicate.
- In the list of tables that displays - or in the Tables to Replicate tab, if you skipped this step during setup - locate a table you want to replicate.
-
To track a table, click the checkbox next to the table’s name. A green checkmark means the table is set to replicate.
-
To track a column, click the checkbox next to the column’s name. A green checkmark means the column is set to replicate.
- Repeat this process for all the tables and columns you want to replicate.
- When finished, click the Finalize Your Selections button at the bottom of the screen to save your selections.
Note: If you change these settings while a replication job is still in progress, they will not be used until the next job starts.
Initial and historical replication jobs
After you finish setting up HubSpot, its Sync Status may show as Pending on either the Stitch Dashboard or in the Integration Details page.
For a new integration, a Pending status indicates that Stitch is in the process of scheduling the initial replication job for the integration. This may take some time to complete.
Initial replication jobs with Anchor Scheduling
If using Anchor Scheduling, an initial replication job may not kick off immediately. This depends on the selected Replication Frequency and Anchor Time. Refer to the Anchor Scheduling documentation for more information.
Free historical data loads
The first seven days of replication, beginning when data is first replicated, are free. Rows replicated from the new integration during this time won’t count towards your quota. Stitch offers this as a way of testing new integrations, measuring usage, and ensuring historical data volumes don’t quickly consume your quota.
HubSpot table schemas
Schemas and versioning
Schemas and naming conventions can change from version to version, so we recommend verifying your integration’s version before continuing.
The schema and info displayed below is for version 2.0 of this integration.
This is the latest version of the HubSpot integraiton.
Custom HubSpot field replication
Custom object properties, or fields, are supported by Stitch’s HubSpot integration. Stitch will query the properties
list for each object and, if custom fields are available through HubSpot’s API, replicate them to your destination.
The data types of these fields will be the same as the data type in HubSpot. For example: A custom field containing date
data will be a date
field in your destination.
This is applicable to any object that supports custom fields in HubSpot.
HubSpot date/date-time values & UNIX timestamps
HubSpot uses UNIX-formatted timestamps in milliseconds to store date
and datetime
data. Stitch doesn’t perform any transformation during the replication process, meaning these values won’t be converted to timestamps before they’re loaded into your destination.
To account for this, consider creating a user-defined function to perform the conversion or building views on top of the raw data.
Table and column names in your destination
Depending on your destination, table and column names may not appear as they are outlined below.
For example: Object names are lowercased in Redshift (CusTomERs
> customers
), while case is maintained in PostgreSQL destinations (CusTomERs
> CusTomERs
). Refer to the Loading Guide for your destination for more info.
campaigns
Replication Method : |
Full Table |
Primary Key : |
id |
API endpoint : |
The campaigns
table contains info about the campaigns in your HubSpot account.
id
The ID of the campaign. Reference: |
|||||||||||
appId
The Application ID for the given email. |
|||||||||||
appName
The Application Name for the given email. |
|||||||||||
contentId
The ID associated with the content. |
|||||||||||
counters
Event count summaries for the given email.
|
|||||||||||
name
The name of the email. |
|||||||||||
numIncluded
The number of included emails. |
|||||||||||
numQueued
The number of queued emails. |
|||||||||||
subType
The subtype of the email. For example: |
|||||||||||
subject
The subject of the email. |
|||||||||||
type
The type of the email. For example: |
companies
Replication Method : |
Key-based Incremental |
Replication Key : |
hs_lastmodifieddate |
Primary Key : |
companyId |
API endpoint : |
The companies
table contains info about the companies your HubSpot contacts belong to.
companyId
The ID of the company. Reference: |
|||
portalId
The ID of the portal the company is associated with. Reference: |
|||
isDeleted
If |
|||
properties
Details about the company.
|
contact_lists
Replication Method : |
Key-based Incremental |
Replication Key : |
updatedAt |
Primary Key : |
listId |
API endpoint : |
The contact_lists
table contains info about the contacts lists in your HubSpot account. Contact lists are used to segment contacts into groups, and there are two types: dynamic (smart lists) and static.
listId
The unique ID of the list. Reference: |
||||||||
updatedAt
The time that the list was last updated. |
||||||||
internalListId
The list’s internal list ID. This field has been deprecated by HubSpot - use |
||||||||
parentId
The ID of the folder that the list belongs to. |
||||||||
metaData
Metadata about the contact list.
|
||||||||
dynamic
Indicates if the contact list is a dynamic list. |
||||||||
name
The name of the contact list. |
||||||||
filters
A list of filters used to define list membership. For example: adding only contacts who have submitted a particular form.
|
||||||||
portalId
The ID of the portal the contact list belongs to. Reference: |
||||||||
createdAt
The time that the list was created. |
||||||||
readOnly
Indicates if the contact list is read-only. |
||||||||
archived
Indicates if the contact list has been archived. |
||||||||
deleteable
Indicates if the list can be deleted. If |
||||||||
listType
The type of list. For example: |
contacts
Replication Method : |
Key-based Incremental |
Replication Key : |
versionTimestamp |
Primary Key : |
canonical-vid |
API endpoint : |
The contacts
table contains info about individual contacts in HubSpot.
Contact properties
If properties have been set for the contact, additional fields beginning with properties__
will be included in the table. Note: Contacts will only have an entry for a property if that property has been set for the contact’s record.
HubSpot always types the value of properties
fields as STRING
despite the property type. Refer to HubSpot’s documentation for more info.
canonical-vid
The canonical ID of the contact. In HubSpot, contacts may have multiple vids, but the Note: When a contact is merged into another contact, the parent contact is updated with the child contact’s vid added to its Reference: |
|||||||||||||||||||||
versionTimestamp
A Unix timestamp in milliseconds of when the contact or its properties was last updated. |
|||||||||||||||||||||
vid
The internal ID of the contact. |
|||||||||||||||||||||
merged-vids
A list of vids that have been merged into this contact record.
|
|||||||||||||||||||||
portal-id
The ID of the portal the contact is associated with. Reference: |
|||||||||||||||||||||
is-contact
Indicates if the contact is a valid contact. |
|||||||||||||||||||||
profile-token
A unique token that can be used to view the contact without logging into HubSpot. |
|||||||||||||||||||||
profile-url
A unique token that can be used to view the contact without logging into HubSpot. Anyone with this URL can view (not edit) the contact’s record. |
|||||||||||||||||||||
identity-profiles
A list of the identities of the contact.
|
|||||||||||||||||||||
list-memberships
A list of the contact’s memberships in contact lists.
|
|||||||||||||||||||||
form-submissions
A list of form submissions for the contact.
|
|||||||||||||||||||||
merge-audits
Details about any merges that have happened for the record.
|
contacts_by_company
Replication Method : |
Full Table |
Primary Key : |
contact-id : company-id |
The contacts_by_company
table contains contact and company ID pairs, allowing you to join contacts to relevant company data.
contact-id
The ID of the contact. Reference: |
company-id
The ID of the company the contact is a part of. Reference: |
Replication Method : |
Key-based Incremental |
Replication Key : |
hs_lastmodifieddate |
Primary Key : |
dealId : portalId |
API endpoint : |
The deals
table contains info about the deals in a HubSpot portal.
dealId
The ID of the deal. Reference: |
|||||||||
portalId
The ID of the portal the deal is associated with. Reference: |
|||||||||
associations
IDs of the Vids, Companies, and Deals associated with the deal.
|
|||||||||
properties
Details about the properties set for the deal.
|
email_events
Replication Method : |
Key-based Incremental |
Replication Key : |
id |
Primary Key : |
id |
API endpoint : |
The email_events
table contains info about email events and how recipients interact with content.
Email events and HubSpot permissions
Replicating this table requires Super Admin permissions in HubSpot. The Super Admin role is different than the Admin role, which you can read more about in HubSpot’s documentation.
If this table is selected and you don’t have Super Admin permissions in HubSpot, an error similar to the following will surface in the integration’s Extraction Logs:
tap - ERROR b'{"status":"error","message":"This oauth-token (**********) does not have proper permissions! (requires any of [email-access])", [...]
id
The ID of the event. |
||||||
appId
The ID of the HubSpot application that sent the email message. |
||||||
appName
The name of the HubSpot application that sent the email message. |
||||||
browser
Details about the browser that serviced the event.
|
||||||
created
The time the event was created. |
||||||
deviceType
The type of device used to service the event. |
||||||
duration
The approximate number of milliseconds the user had opened the email message. |
||||||
emailCampaignId
The ID of the email campaign that the email message is a part of. Reference: |
||||||
emailCampaignGroupId
The ID of the email campaign group associated with the email message. |
||||||
filteredEvent
Indicates if the event was filtered. |
||||||
from
The |
||||||
hmid
An auto-generated ID that corresponds to the header |
||||||
ipAddress
The IP address where the event originated. |
||||||
linkId
The ID of the link the recipient clicked in the email message. |
||||||
location
Details about where the event occurred, including the city, state, and country.
|
||||||
portalId
The ID of the HubSpot portal that sent the email message. Reference: |
||||||
recipient
The email address of the recipient of the email message. |
||||||
response
The full response from the recipient’s email server. |
||||||
sentBy
Details about the email message’s
|
||||||
smtpId
The ID that HubSpot attaches to the email message. |
||||||
subject
The subject line of the email message. |
||||||
type
The type of event. Click the link in attribute’s name for more details about email event types. |
||||||
url
The URL in the email message that the recipient clicked. |
||||||
userAgent
The user agent responsible for the event. |
engagements
Replication Method : |
Key-based Incremental |
Replication Key : |
lastUpdated |
Primary Key : |
id |
API endpoint : |
The engagements
table contains info about all the engagements in a HubSpot portal.
id
The ID for the engagement. |
|||||||||||||||||||||||||
lastUpdated
The time the engagement was last updated. |
|||||||||||||||||||||||||
portalId
The ID of the portal the engagement belongs to. Reference: |
|||||||||||||||||||||||||
active
Indicates if the engagement is active. |
|||||||||||||||||||||||||
createdAt
The time the engagement was created. |
|||||||||||||||||||||||||
ownerId
The ID of the owner associated with the engagement. Reference: |
|||||||||||||||||||||||||
type
The type of engagement. For example: |
|||||||||||||||||||||||||
timestamp
The time the engagement should appear in the timeline. |
|||||||||||||||||||||||||
associations
IDs of the objects associated with the engagement. For example: contacts, deals.
|
|||||||||||||||||||||||||
attachments
For
|
|||||||||||||||||||||||||
metadata
Metadata about the engagement.
|
Replication Method : |
Key-based Incremental |
Replication Key : |
updatedAt |
Primary Key : |
guid |
API endpoint : |
The forms
table contains info about your HubSpot website forms.
guid
The GUID of the form. Reference: |
|||||||||||||||||||||||||||||||||||
updatedAt
The time the form was last updated. |
|||||||||||||||||||||||||||||||||||
deletedAt
If the form was deleted, the time that the deletion took place. |
|||||||||||||||||||||||||||||||||||
portalId
The ID of the portal the form belongs to. Reference: |
|||||||||||||||||||||||||||||||||||
name
The name of the form. |
|||||||||||||||||||||||||||||||||||
action
Deprecated by HubSpot. |
|||||||||||||||||||||||||||||||||||
method
The API method used to send the form submission. For example: |
|||||||||||||||||||||||||||||||||||
cssClass
The CSS class associated with the form. |
|||||||||||||||||||||||||||||||||||
redirect
The URL that the visitor will be redirect to after filling out the form. |
|||||||||||||||||||||||||||||||||||
submitText
The text that displays to the end-user to submit the form. For example: |
|||||||||||||||||||||||||||||||||||
followUpId
Deprecated by HubSpot. |
|||||||||||||||||||||||||||||||||||
notifyRecipients
A list of email addresses that should receive submission notifications. |
|||||||||||||||||||||||||||||||||||
leadNurturingCampaignId
The ID of the lead nurturing campaign the form is associated with. Reference: |
|||||||||||||||||||||||||||||||||||
formFieldGroups
Details about the fields in the form.
|
|||||||||||||||||||||||||||||||||||
createdAt
The time the form was created. |
|||||||||||||||||||||||||||||||||||
performableHtml
Deprecated by HubSpot. |
|||||||||||||||||||||||||||||||||||
migratedFrom
Deprecated by HubSpot. |
|||||||||||||||||||||||||||||||||||
ignoreCurrentValues
Indicates if the form will pre-populate fields with known values for known contacts. |
|||||||||||||||||||||||||||||||||||
deleteable
Indicates if the form is deleteable. |
|||||||||||||||||||||||||||||||||||
inlineMessage
The ‘thank you’ message that displays on the page after the form is submitted. |
|||||||||||||||||||||||||||||||||||
tmsId
Deprecated by HubSpot. |
|||||||||||||||||||||||||||||||||||
captchaEnabled
Indicates if a Captcha is enabled on the form. |
|||||||||||||||||||||||||||||||||||
campaignGuid
The GUID of the campaign the form is associated with. |
|||||||||||||||||||||||||||||||||||
cloneable
Indicates if the form is cloneable. |
|||||||||||||||||||||||||||||||||||
editable
Indicates if the form is editable. |
|||||||||||||||||||||||||||||||||||
formType
The type of form. For example: |
|||||||||||||||||||||||||||||||||||
metaData
Metadata about the form.
|
owners
Replication Method : |
Key-based Incremental |
Replication Key : |
updatedAt |
Primary Key : |
ownerId : portalId |
API endpoint : |
The owners
table contains info about the owners that exist in your HubSpot portal. Owners are created and updated in HubSpot when new users are added or when owners are synced from Salesforce to HubSpot.
ownerId
The ID of the owner. Reference: |
|||||
portalId
The ID of the portal the owner is associated with. Reference: |
|||||
updatedAt
The time that the owner was last updated in HubSpot. |
|||||
type
The type of owner. For example: |
|||||
firstName
The first name of the owner. |
|||||
lastName
The last name of the owner. |
|||||
email
The email address associated with the owner. |
|||||
createdAt
The time that the owner was created in HubSpot. |
|||||
signature
The owner’s signature. |
|||||
hasContactsAccess
Indicates if the owner has access to the contacts in the HubSpot portal. |
|||||
remoteList
Details about the remote list associated with the owner.
|
subscription_changes
Replication Method : |
Key-based Incremental |
Replication Key : |
timestamp |
Primary Key : |
recipient : portalId : timestamp |
API endpoint : |
The subscription_changes
table contains info about changes made subscriptions.
recipient
The contact associated with the subscription change event. |
|||||||||
portalId
The ID of the portal associated with the subscription change event. Reference: |
|||||||||
timestamp
The time that the subscription change event occurred. |
|||||||||
changes
Details about the subscription change event.
|
workflows
Replication Method : |
Key-based Incremental |
Replication Key : |
updatedAt |
Primary Key : |
id |
API endpoint : |
The workflows
table contains info about the workflows in your HubSpot portal.
id
The ID of the workflow. |
||||
updatedAt
The time that the workflow was last updated. |
||||
name
The name of the workflow. |
||||
type
The type of workflow. For example: |
||||
enabled
Indicates if the workflow is enabled in your HubSpot portal. |
||||
inserted-at
The time that the workflow was inserted. |
||||
personaTagIds
Info about the personas tied to the workflow.
|
||||
contactListIds
Summary info for the contact lists associated with the workflow.
|
Related | Troubleshooting |
Questions? Feedback?
Did this article help? If you have questions or feedback, feel free to submit a pull request with your suggestions, open an issue on GitHub, or reach out to us.