HubSpot

This page contains the setup guide and reference information for HubSpot.

Features

Feature	Supported?
Full Refresh Sync	Yes
Incremental Sync	Yes
Namespaces	No

There are two types of incremental sync:

• Incremental (standard server-side, where API returns only the data updated or generated since the last sync)
• Client-Side Incremental (API returns all available data and connector filters out only new records)

Prerequisites

• A private HubSpot app with Access Token, OR

Setup guide

Step 1: Create a HubSpot App

Follow these instructions or the below steps to create a HubSpot App and obtain the Access Token needed to set up the source in Daspire.

1. In your HubSpot account, click the settings icon in the top navigation bar.

2. In the left sidebar menu, navigate to Integrations > Private Apps.

3. Click Create private app.

4. On the Basic Info tab, enter your app's name.

5. Click the Scopes tab. Select the Read checkbox for each scope you want your private app to be able to access.

   NOTE: Daspire needs the following Scopes to be able to sync all the streams listed below.

Stream	Scope
campaigns	content
companies	crm.objects.companies.read, crm.schemas.companies.read
contact_lists	crm.objects.lists.read
contacts	crm.objects.contacts.read
contacts_list_memberships	crm.objects.contacts.read
Custom CRM Objects	crm.objects.custom.read
deal_pipelines	crm.objects.contacts.read
deals	crm.objects.deals.read, crm.schemas.deals.read
deals_archived	crm.objects.deals.read, crm.schemas.deals.read
email_events	content
email_subscriptions	content
engagements	crm.objects.companies.read, crm.objects.contacts.read, crm.objects.deals.read, tickets, e-commerce
engagements_emails	sales-email-read
forms	forms
form_submissions	forms
goals	crm.objects.goals.read
line_items	e-commerce
owners	crm.objects.owners.read
products	e-commerce
property_history	crm.objects.contacts.read
subscription_changes	content
tickets	tickets
workflows	automation

6. After you're done configuring your app, click Create app on the top right.

7. Once your private app is created, you will get an Access Token. Copy that. You will use it to set up the source in Daspire.

Step 2: Set up HubSpot in Daspire

1. Select HubSpot from the Source list.

2. Enter a Source Name.

3. To authenticate using a Private App, enter the Access Token for your HubSpot account you obtained in Step 1.

4. For Start date, enter the date in the following format: yyyy-mm-ddThh:mm:ssZ. The data added on and after this date will be replicated.

5. Click Save & Test.

Supported streams

This source is capable of syncing the following streams:

• Campaigns (Client-Side Incremental)
• Companies (Incremental)
• Contact Lists (Incremental)
• Contacts (Incremental)
• Contacts List Memberships
• Deal Pipelines (Client-Side Incremental)
• Deals (including Contact associations) (Incremental)
• Deals Archived (including Contact associations) (Incremental)
• Email Events (Incremental)
• Email Subscriptions
• Engagements (Incremental)
• Engagements Calls (Incremental)
• Engagements Emails (Incremental)
• Engagements Meetings (Incremental)
• Engagements Notes (Incremental)
• Engagements Tasks (Incremental)
• Forms (Client-Side Incremental)
• Form Submissions (Client-Side Incremental)
• Goals (Incremental)
• Line Items (Incremental)
• Marketing Emails
• Owners (Client-Side Incremental)
• Products (Incremental)
• Property History (Incremental)
• Subscription Changes (Incremental)
• Tickets (Incremental)
• Ticket Pipelines (Client-Side Incremental)
• Workflows (Client-Side Incremental)
• ContactsWebAnalytics (Incremental)
• CompaniesWebAnalytics (Incremental)
• DealsWebAnalytics (Incremental)
• TicketsWebAnalytics (Incremental)
• EngagementsCallsWebAnalytics (Incremental)
• EngagementsEmailsWebAnalytics (Incremental)
• EngagementsMeetingsWebAnalytics (Incremental)
• EngagementsNotesWebAnalytics (Incremental)
• EngagementsTasksWebAnalytics (Incremental)
• GoalsWebAnalytics (Incremental)
• LineItemsWebAnalytics (Incremental)
• ProductsWebAnalytics (Incremental)

Notes on the engagements stream

1. Objects in the engagements stream can have one of the following types: note, email, task, meeting, call. Depending on the type of engagement, different properties are set for that object in the engagements_metadata table in the destination:

• A call engagement has a corresponding engagements_metadata object with non-null values in the toNumber, fromNumber, status, externalId, durationMilliseconds, externalAccountId, recordingUrl, body, and disposition columns.
• An email engagement has a corresponding engagements_metadata object with non-null values in the subject, html, and text columns. In addition, there will be records in four related tables, engagements_metadata_from, engagements_metadata_to, engagements_metadata_cc, engagements_metadata_bcc.
• A meeting engagement has a corresponding engagements_metadata object with non-null values in the body, startTime, endTime, and title columns.
• A note engagement has a corresponding engagements_metadata object with non-null values in the body column.
• A task engagement has a corresponding engagements_metadata object with non-null values in the body, status, and forObjectType columns.

2. The engagements stream uses two different APIs based on the length of time since the last sync and the number of records which Daspire hasn't yet synced.

• EngagementsRecent if the following two criteria are met:

  • The last sync was performed within the last 30 days
  • Fewer than 10,000 records are being synced

• EngagementsAll if either of these criteria are not met.

  Because of this, the engagements stream can be slow to sync if it hasn't synced within the last 30 days and/or is generating large volumes of new data. We therefore recommend scheduling frequent syncs.

Performance considerations

1. Rate limiting

The integration is restricted by normal HubSpot rate limitations.

Troubleshooting

1. Enabling streams: Some streams, such as `workflows``, need to be enabled before they can be read using an integration authenticated using an API Key. If reading a stream that is not enabled, a log message returned to the output and the sync operation will only sync the other streams available.

Example of the output message when trying to read workflows stream with missing permissions for the API Key:

{
    "type": "LOG",
    "log": {
        "level": "WARN",
        "message": "Stream `workflows` cannot be proceed. This API Key (EXAMPLE_API_KEY) does not have proper permissions! (requires any of [automation-access])"
    }
}

2. Unnesting top level properties: Since version 1.5.0, in order to not make the users query their destinations for complicated json fields, we duplicate most of nested data as top level fields.

For instance:

{
  "id": 1,
  "updatedAt": "2020-01-01",
  "properties": {
    "hs_note_body": "World's best boss",
    "hs_created_by": "Michael Scott"
  }
}

becomes

{
    "id": 1,
    "updatedAt": "2020-01-01",
    "properties": {
      "hs_note_body": "World's best boss",
      "hs_created_by": "Michael Scott"
    },
    "properties_hs_note_body": "World's best boss",
    "properties_hs_created_by": "Michael Scott"
}

3. 403 Forbidden Error

• Hubspot has scopes for each API call.

• Each stream is tied to a scope and will need access to that scope to sync data.

• Review the Hubspot OAuth scope documentation here.

• Additional permissions:

  • feedback_submissions: Service Hub Professional account

  • marketing_emails: Market Hub Starter account

  • workflows: Sales, Service, and Marketing Hub Professional accounts

4. Max number of tables that can be synced at a time is 6,000. We advise you to adjust your settings if it fails to fetch schema due to max number of tables reached.