Airbyte connectors
Hubspot

HubSpot

Overview

This page guides you through setting up the HubSpot source.

Features

Feature NameSupported
Full ImportYes
Incremental ImportYes
Start Date SelectionYes

Supported streams

Custom CRM Objects will appear as streams available for sync, alongside the standard objects listed above.

Getting started

Requirements and prerequisites

  1. One of the following two types of credentials:
    • OAuth 2.0 credentials
    • A Private App to authenticate your HubSpot account
  2. If you are using either OAuth or Private App authentication, you need to configure the appropriate scopes (opens in a new tab) for the following streams:
StreamRequired Scope
campaignscontent
companiescrm.objects.companies.read, crm.schemas.companies.read
contact_listscrm.objects.lists.read
contactscrm.objects.contacts.read
contacts_list_membershipscrm.objects.contacts.read
Custom CRM OBjectscrm.objects.custom.read
deal_pipelinescrm.objects.contacts.read
dealscrm.objects.deals.read, crm.schemas.deals.read
deals_archivedcrm.objects.deals.read, crm.schemas.deals.read
email_eventscontent
email_subscriptionscontent
engagementscrm.objects.companies.read, crm.objects.contacts.read, crm.objects.deals.read, tickets, e-commerce
engagements_emailssales-email-read
formsforms
form_submissionsforms
goalscrm.objects.goals.read
line_itemse-commerce
ownerscrm.objects.owners.read
productse-commerce
property_historycrm.objects.contacts.read
subscription_changescontent
ticketstickets
workflowsautomation

Set up guide

  1. Create a new source, select Hubspot (Airbyte) from the Source type dropdown and enter a name for it.
  2. On the source setup page, create a new Hubspot secret, enter a unique name for it.
  3. Select a Start date.
  4. You can use OAuth or a Private Apps to authenticate your HubSpot account.
    • To authenticate using OAuth, ensure you have set the appropriate scopes for HubSpot, select OAuth option and click Authorise with Hubspot.
    • To authenticate using a Private App, select Private App and enter the Access Token for your HubSpot account which you can obtain by following the instructions provided by Hubspot here (opens in a new tab).

Limitations

Engagements stream limitations:

  • 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 is 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.
  • In order to perform incremental sync for Engagements, it should be scheduled no rarer than once every 30 days, and should not sync more than 10k new records. If this is the case, EngagementsRecent endpoint can be called. Otherwise, a different API endpoint is called (EngagementsAll) and all records are synced.

Performance considerations

The connector is restricted by normal HubSpot rate limitations (opens in a new tab).

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

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


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

Rate limits

HubSpot's API will rate limit (opens in a new tab) the amount of records you can sync daily, so make sure that you are on the appropriate plan if you are planning on syncing more than 250,000 records per day.

Google SheetsJira