Skip to content
sandadocs
Console Start free trial

HubSpot

Bring contacts, companies, deals, tickets and engagement activity from HubSpot into your warehouse.

View as Markdown

Before you start

The simplest way to connect HubSpot is a private app. It is an access token, scoped to the data you choose, that belongs to your HubSpot account. The form's Authentication field opens on Private App.

  • Permission to create private apps. This is usually a super admin in your HubSpot account.
  • A private app with read scopes. In your HubSpot account settings, under Integrations, open Private Apps and create one. If HubSpot has moved this screen, search its settings for private apps. Give the app read scopes for the data you want in sanda, for example crm.objects.contacts.read, crm.objects.companies.read and crm.objects.deals.read. sanda only ever reads.
  • The access token. Once the app is created, open its Auth tab and reveal the token. HubSpot issues one token per private app, and that token is the whole credential.

If you already run a HubSpot developer application, the OAuth option takes its Client ID and Client Secret, plus a Refresh Token you have obtained through HubSpot's authorisation flow.

Connect HubSpot

  1. Choose HubSpot. Go to Data · Connections, press New connection and pick HubSpot.
  2. Choose how to sign in. Leave Authentication on Private App and paste the token into Access token. For the other option, choose OAuth and fill in Client ID, Client Secret and Refresh Token.
  3. Choose how far back to load. Start date is under Advanced settings. Enter a UTC date and time, in the form 2017-01-25T00:00:00Z. When it is empty, sanda starts from 2006-06-01, HubSpot's creation date, so choose a date that fits your data.
  4. Continue. Press Continue, name the connection, and press Read schema. sanda signs in and lists the HubSpot objects the token can read. If it fails, the message says why. See Troubleshoot connections.

The rest of the flow, naming the connection, setting a frequency and choosing streams, is the same for every source. See Add a connection.

What syncs

Each HubSpot object becomes a stream, and lands in your warehouse as its own table. The usual starting points are contacts, companies and deals. The stream list shows everything the token can read, so a scope you did not grant means a stream you will not be able to sync. Add the scope to the private app when you want more.

Enable experimental streams, under Advanced settings, makes HubSpot's experimental streams available for sync. It opens off.

Tips

  • Choose a real start date. Starting from 2006 makes the first load as long as it can be. A date near when you began using HubSpot is usually enough.
  • Recover records that arrive late. CRM Search Lookback Window (minutes) re-fetches records from the last N minutes on each incremental run. Use it if you notice missing records in contacts, companies, deals or tickets. Property History Lookback Window (minutes) does the same for property history streams.
  • Type mismatches. If HubSpot returns values that do not match a property's declared type, and the load rejects the records, turn on Treat dynamic number and boolean properties as strings under Advanced settings. After changing it, refresh the source schema and the affected stream data.
  • Keep the token safe. Anyone with the token can read what its scopes allow. If it leaks, rotate it in the private app, then update the connection.

Configuration fields

What the connection form asks for. Required fields are marked; the rest are optional.

Field Type Required Description
Association Between Objects Streams array No
Authentication one of 2 options Yes Choose how to authenticate to HubSpot.
Custom Object Association Streams array No
Enable experimental streams boolean No If enabled then experimental streams become available for sync. Default false.
CRM Search Lookback Window (minutes) integer No How far back (in minutes) to re-fetch records during incremental syncs for CRM Search streams (e.g. contacts, companies, deals, tickets). Set this if you notice missing records in CRM Search streams to recover data that may be delayed by the HubSpot API. Does not affect property history streams. Default 0.
Number of concurrent threads integer No The number of worker threads to use for the sync. Default 10.
Property History Lookback Window (minutes) integer No How far back (in minutes) to re-fetch records during incremental syncs for property history streams (deals, contacts, companies property history). Set this if you notice missing records in property history streams caused by cursor drift from HubSpot calculated properties. Default 0.
Start date string No UTC date and time in the format 2017-01-25T00:00:00Z. Any data before this date will not be replicated. If not set, "2006-06-01T00:00:00Z" (Hubspot creation date) will be used as start date. It's recommended to provide relevant to your data start date value to optimize synchronization.
Treat dynamic number and boolean properties as strings boolean No If enabled, HubSpot dynamic number and boolean properties are exposed as string. Useful when HubSpot returns values that do not match the declared type and the destination rejects the records. Default false.

Authentication

Choose how to authenticate to HubSpot.

Choose one of the following. Each asks for its own fields.

OAuth

Field Type Required Description
Client ID string Yes The Client ID of your HubSpot developer application.
Client Secret string, secret Yes The client secret for your HubSpot developer application.
Refresh Token string, secret Yes Refresh token to renew an expired access token.

Private App

Field Type Required Description
Access token string, secret Yes HubSpot Access token.

Something unclear or out of date? Tell us, and we will fix the page.