Skip to main content

HubSpot

This page guides you through setting up the HubSpot source connector.

Prerequisite​

You can use OAuth, API key, or Private App to authenticate your HubSpot account. If you choose to use OAuth or Private App, you need to configure the appropriate scopes 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
deal_pipelineseither the crm.objects.contacts.read scope (to fetch deals pipelines) or the tickets scope.
dealscrm.objects.deals.read, crm.schemas.deals.read
email_eventscontent
engagementscrm.objects.companies.read, crm.objects.contacts.read, crm.objects.deals.read, tickets, e-commerce
engagements_emailssales-email-read
formsforms
form_submissionsforms
line_itemse-commerce
ownerscrm.objects.owners.read
productse-commerce
property_historycrm.objects.contacts.read
subscription_changescontent
ticketstickets
workflowsautomation

Set up the HubSpot source connector​

  1. Log into your Airbyte Cloud or Airbyte Open Source account.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select HubSpot from the Source type dropdown.
  4. Enter a name for your source.
  5. For Start date, enter the date in YYYY-MM-DDTHH:mm:ssZ format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data.
  6. You can use OAuth or an API key to authenticate your HubSpot account. We recommend using OAuth for Airbyte Cloud and an API key for Airbyte Open Source.
    • To authenticate using OAuth for Airbyte Cloud, ensure you have set the appropriate scopes for HubSpot and then click Authenticate your HubSpot account to sign in with HubSpot and authorize your account.
    • To authenticate using an API key for Airbyte Open Source, select API key from the Authentication dropdown and enter the API key for your HubSpot account.
      note

      Check the performance considerations before using an API key.

  7. Click Set up source.

Supported sync modes​

The HubSpot source connector supports the following sync modes:

  • Full Refresh
  • Incremental

Supported Streams​

The HubSpot source connector supports the following streams:

A note on the engagements stream​

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.

New state strategy on Incremental streams​

Due to some data loss because an entity was updated during the synch, instead of updating the state by reading the latest record the state will be save with the initial synch time. With the proposed state strategy, it would capture all possible updated entities in incremental synch.

Performance considerations​

The connector is restricted by normal HubSpot rate limitations.

Some streams, such as workflows need to be enabled before they can be read using a connector 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 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])'
    }
}

HubSpot's API will rate limit 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.

Tutorials​

Now that you have set up the Hubspot source connector, check out the following Hubspot tutorial:

Build a single customer view with open-source tools

Changelog​

VersionDatePull RequestSubject
0.3.22023-02-0722479Turn on default HttpAvailabilityStrategy
0.3.12023-01-2722009Set AvailabilityStrategy for streams explicitly to None
0.3.02022-10-2718546Sunsetting API Key authentication. Quotes stream is no longer available
0.2.22022-10-0316914Fix 403 forbidden error validation
0.2.12022-09-2617120Migrate to per-stream state.
0.2.02022-09-1316632Remove Feedback Submissions stream as the one using unstable (beta) API.
0.1.832022-09-0116214Update Tickets, fix missing properties and change how state is updated.
0.1.822022-08-1815110Check if it has a state on search streams before first sync
0.1.812022-08-0515354Fix Deals stream schema
0.1.802022-08-0115156Fix 401 error while retrieving associations using OAuth
0.1.792022-07-2815144Revert v0.1.78 due to permission issues
0.1.782022-07-2815099Fix to fetch associations when using incremental mode
0.1.772022-07-2615035Make PropertyHistory stream read historic data not limited to 30 days
0.1.762022-07-2514999Partially revert changes made in v0.1.75
0.1.752022-07-1814744Remove override of private CDK method
0.1.742022-07-2514412Add private app authentication
0.1.732022-07-1314666Decrease number of http requests made, disable Incremental mode for PropertyHistory stream
0.1.722022-06-2414054Extended error logging
0.1.712022-06-2414102Removed legacy AirbyteSentry dependency from the code
0.1.702022-06-1613837Fix the missing data in CRM streams issue
0.1.692022-06-1013691Fix the URI Too Long issue
0.1.682022-06-0813596Fix for the property_history which did not emit records
0.1.672022-06-0713566Report which scopes are missing to the user
0.1.662022-06-0513475Scope crm.objects.feedback_submissions.read added for feedback_submissions stream
0.1.652022-06-0313455Discover only returns streams for which required scopes were granted
0.1.642022-06-0313218Transform contact_lists data to comply with schema
0.1.632022-06-0213320Fix connector incremental state handling
0.1.622022-06-0113383Add line items to deals stream
0.1.612022-05-2513381Requests scopes as optional instead of required
0.1.602022-05-2513159Use RFC3339 datetime
0.1.592022-05-1012711Ensure oauth2.0 token has all needed scopes in "check" command
0.1.582022-05-0412482Update input configuration copy
0.1.572022-05-0412198Add deals associations for quotes
0.1.562022-05-0212515Extra logs for troubleshooting 403 errors
0.1.552022-04-2812424Correct schema for ticket_pipeline stream
0.1.542022-04-2812335Mock time slep in unit test s
0.1.532022-04-2012230Change spec json to yaml format
0.1.522022-03-2511423Add tickets associations to engagements streams
0.1.512022-03-2411321Fix updated at field non exists issue
0.1.502022-03-2211266Fix Engagements Stream Pagination
0.1.492022-03-1711218Anchor hyperlink in input configuration
0.1.482022-03-1611105Fix float numbers, upd docs
0.1.472022-03-1511121Add partition keys where appropriate
0.1.462022-03-1410700Handle 10k+ records reading in Hubspot streams
0.1.452022-03-0410707Remove stage history from deals stream to increase efficiency
0.1.442022-02-249027Add associations companies to deals, ticket and contact stream
0.1.432022-02-2410576Cast timestamp to date/datetime
0.1.422022-02-2210492Add date-time format to datetime fields
0.1.412022-02-2110177Migrate to CDK
0.1.402022-02-1010142Add associations to ticket stream
0.1.392022-02-1010055Bug fix: reading not initialized stream
0.1.382022-02-039786Add new streams for engagements(calls, emails, meetings, notes and tasks)
0.1.372022-01-279555Getting form_submission for all forms
0.1.362022-01-227784Add Property History Stream
0.1.352021-12-249081Add Feedback Submissions stream and update Ticket Pipelines stream
0.1.342022-01-209641Add more fields for email_events stream
0.1.332022-01-148887More efficient support for incremental updates on Companies, Contact, Deals and Engagement streams
0.1.322022-01-138011Add new stream form_submissions
0.1.312022-01-119385Remove auto-generated properties from Engagements stream
0.1.302021-01-109129Created Contacts list memberships streams
0.1.292021-12-178699Add incremental sync support for companies, contact_lists, contacts, deals, line_items, products, quotes, tickets streams
0.1.282021-12-158429Update fields and descriptions
0.1.272021-12-098658Fixed config backward compatibility issue by allowing additional properties in the spec
0.1.262021-11-308329Removed 'skip_dynamic_fields' config param
0.1.252021-11-238216Add skip dynamic fields for testing only
0.1.242021-11-097683Fix name issue 'Hubspot' -> 'HubSpot'
0.1.232021-11-087730Fix OAuth flow schema
0.1.222021-11-037562Migrate Hubspot source to CDK structure
0.1.212021-10-277405Change of package import from urllib to urllib.parse
0.1.202021-10-267393Hotfix for split_properties function, add the length of separator symbol ,(%2C in HTTP format) to the checking of the summary URL length
0.1.192021-10-266954Fix issue with getting 414 HTTP error for streams
0.1.182021-10-185840Add new marketing emails (with statistics) stream
0.1.172021-10-146995Update discover method: disable quotes stream when using OAuth config
0.1.162021-09-276465Implement OAuth support. Use CDK authenticator instead of connector specific authenticator
0.1.152021-09-236374Use correct schema for owners stream
0.1.142021-09-085693Include deal_to_contact association when pulling deal stream and include contact ID in contact stream
0.1.132021-09-085834Fixed array fields without items property in schema
0.1.122021-09-025798Treat empty string values as None for field with format to fix normalization errors
0.1.112021-08-265685Remove all date-time format from schemas
0.1.102021-08-175463Fix fail on reading stream using API Key without required permissions
0.1.92021-08-115334Fix empty strings inside float datatype
0.1.82021-08-065250Fix issue with printing exceptions
0.1.72021-07-274913Update fields schema