HubSpot
This page contains the setup guide and reference information for the HubSpot source connector.
Prerequisites
- HubSpot Account
- For Airbyte Open Source: a Private App access token or a Service Key
Setup guide
Step 1: Set up HubSpot
For Airbyte Cloud:
- OAuth (Recommended). We highly recommend you use OAuth rather than Private App authentication, as it significantly simplifies the setup process.
- Private App: If you are using a Private App, you will need to use your Access Token to set up the connector. Please refer to the official HubSpot documentation to learn how to obtain the access token. If your HubSpot account can no longer create Private Apps, create a Service Key instead and enter it in the same Access token field.
For Airbyte Open Source:
- Private App setup (Recommended): If you are authenticating via a Private App, you will need to use your Access Token to set up the connector. Please refer to the official HubSpot documentation to learn how to obtain the access token. If your HubSpot account can no longer create Private Apps, create a Service Key instead and enter it in the same Access token field.
- OAuth setup: If you are using OAuth to authenticate on Airbyte Open Source, please refer to HubSpot's detailed walkthrough. To set up the connector, you will need to acquire your:
- Client ID
- Client Secret
- Refresh Token
For more details, refer to HubSpot's authentication documentation.
Service keys
HubSpot is retiring the creation of legacy Private Apps: accounts created on or after September 28, 2026 can't create new Private Apps from that date, and all other accounts lose the ability on October 26, 2026. Existing Private Apps and their access tokens keep working.
For accounts that can't create a Private App, use a HubSpot Service Key (public beta). A Service Key is a static bearer token with the same pat- format and the same per-object scopes as a Private App access token, so the connector accepts it without any special configuration:
- In HubSpot, go to Development, then Keys > Service keys, and click Create service key.
- Add the scopes for the streams you want to sync (see Step 2). HubSpot has deprecated the legacy
ticketsande-commercescopes, so the Service Key scope picker might not offer them; Step 2 lists their granular replacements. - Create the key, click Show, and copy it.
- In Airbyte, choose the Private App authentication method and paste the Service Key into the Access token field.
A Service Key can only carry scopes that your HubSpot account and user already have. If HubSpot returns 403 for a stream, first confirm that the key has the scope listed in Step 2. If the scope is present, your account's subscription tier most likely doesn't include that object (for example, the leads stream needs the Leads object, which requires Sales Hub Professional or Enterprise).
Step 2: Configure the scopes for your streams (Private App and Service Key only)
These instructions are only relevant if you are using a Private App or a Service Key for authentication. You can ignore this if you are authenticating via OAuth.
To set up a Private App or Service Key, you must manually configure scopes to ensure Airbyte can sync all available data. Each scope relates to a specific stream or streams. Refer to HubSpot's documentation on scopes for instructions.
The legacy tickets and e-commerce scopes are deprecated and might not be available when you create a Service Key. Where the table lists tickets, grant crm.objects.tickets.read (and crm.schemas.tickets.read for ticket properties and pipelines). Where it lists e-commerce, grant crm.objects.products.read, crm.objects.line_items.read, and crm.schemas.line_items.read.
Expand to review scopes
| Stream | Required Scope |
|---|---|
campaigns | content |
companies | crm.objects.companies.read, crm.schemas.companies.read |
contact_lists | crm.lists.read |
contacts | crm.objects.contacts.read |
association_streams | Read scopes for the selected source and target objects |
| Custom CRM Objects | crm.objects.custom.read |
custom_object_association_streams | crm.objects.custom.read and the read scope for any selected standard object |
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 |
engagements_task_pipelines | crm.objects.contacts.read |
forms | forms |
form_submissions | forms |
goals | crm.objects.goals.read |
leads | crm.objects.leads.read, crm.schemas.leads.read |
list_memberships | crm.lists.read |
line_items | e-commerce |
listings | crm.objects.listings.read |
owners | crm.objects.owners.read |
products | e-commerce |
contacts_property_history | crm.objects.contacts.read |
companies_property_history | crm.objects.companies.read |
deals_property_history | crm.objects.deals.read |
subscription_changes | content |
tickets | tickets |
users | crm.objects.users.read, settings.users.read |
account_details | oauth |
deal_splits | crm.objects.deals.read |
properties | No additional scopes required |
workflows | automation |
flows | automation (plus *.sensitive.read for flows touching sensitive data) |
contacts_web_analytics | business-intelligence, crm.objects.contacts.read |
companies_web_analytics | business-intelligence, crm.objects.companies.read |
deals_web_analytics | business-intelligence, crm.objects.deals.read |
tickets_web_analytics | business-intelligence, tickets |
engagements_calls_web_analytics | business-intelligence, crm.objects.contacts.read |
engagements_emails_web_analytics | business-intelligence, crm.objects.contacts.read, sales-email-read |
engagements_meetings_web_analytics | business-intelligence, crm.objects.contacts.read |
engagements_notes_web_analytics | business-intelligence, crm.objects.contacts.read |
engagements_tasks_web_analytics | business-intelligence, crm.objects.contacts.read |
goals_web_analytics | business-intelligence, crm.objects.goals.read |
line_items_web_analytics | business-intelligence, e-commerce, crm.objects.line_items.read |
products_web_analytics | business-intelligence, e-commerce |
Step 3: Set up the HubSpot connector in Airbyte
For Airbyte Cloud:
- Log into your Airbyte Cloud account.
- Click Sources and then click + New source.
- On the Set up the source page, select HubSpot from the Source type dropdown.
- Enter a name for the HubSpot connector.
- From the Authentication dropdown, select your chosen authentication method:
-
(Recommended) To authenticate using OAuth, select OAuth and click Authenticate your HubSpot account to sign in with HubSpot and authorize your account.
HubSpot Authentication issuesYou may encounter an error during the authentication process in the popup window with the message
An invalid scope name was provided. To resolve this, close the window and retry authentication. -
(Not Recommended) To authenticate using a Private App, select Private App and enter the Access Token for your HubSpot account. A Service Key goes in the same field.
-
- (Optional) For Start date, use the provided datepicker or enter the date in the following format:
yyyy-mm-ddThh:mm:ssZ. Data added on and after this date will be replicated. If this is not set, "2006-06-01T00:00:00Z" (the date HubSpot was created) will be used as a start date.
- (Optional) Set the CRM Search Lookback Window in minutes to re-fetch data for CRM Search streams (e.g. contacts, companies, deals, tickets) for a specified number of minutes before the state from the previous sync. This helps capture missing records in CRM Search streams.
- (Optional) Set the Property History Lookback Window in minutes to re-fetch data for property history streams (
deals_property_history,contacts_property_history,companies_property_history). This helps capture records that may be missed due to cursor drift caused by HubSpot calculated properties. A value of43200(30 days) is a reasonable starting point. - (Optional) Enable Treat dynamic number and boolean properties as strings if your destination rejects records because HubSpot returns values that don't match the declared
numberorbooleantype. See Destination type conversion errors in Troubleshooting for details. - Click Set up source and wait for the tests to complete.
For Airbyte Open Source:
- Navigate to the Airbyte Open Source dashboard.
- From the Airbyte UI, click Sources, then click on + New Source and select HubSpot from the list of available sources.
- Enter a Source name of your choosing.
- From the Authentication dropdown, select your chosen authentication method:
- (Recommended) To authenticate using a Private App, select Private App and enter the Access Token for your HubSpot account. A Service Key goes in the same field.
- (Not Recommended:) To authenticate using OAuth, select OAuth and enter your Client ID, Client Secret, and Refresh Token.
- (Optional) For Start date, use the provided datepicker or enter the date in the following format:
yyyy-mm-ddThh:mm:ssZ. The data added on and after this date will be replicated. If not set, "2006-06-01T00:00:00Z" (HubSpot creation date) will be used as start date. It's recommended to provide a start date relevant to your data to optimize synchronization. - (Optional) Set the CRM Search Lookback Window in minutes to re-fetch data for CRM Search streams (e.g. contacts, companies, deals, tickets) for a specified number of minutes before the state from the previous sync. This helps capture missing records in CRM Search streams.
- (Optional) Set the Property History Lookback Window in minutes to re-fetch data for property history streams (
deals_property_history,contacts_property_history,companies_property_history). This helps capture records that may be missed due to cursor drift caused by HubSpot calculated properties. A value of43200(30 days) is a reasonable starting point. - (Optional) Enable Treat dynamic number and boolean properties as strings if your destination rejects records because HubSpot returns values that don't match the declared
numberorbooleantype. See Destination type conversion errors in Troubleshooting for details. - Click Set up source and wait for the tests to complete.
Experimental streams
Enable the Enable experimental streams toggle to sync the Web Analytics streams. These read HubSpot's Events API (/events/event-occurrences/2026-03) and emit web analytics events (page views and form submissions) for each parent object:
contacts_web_analyticscompanies_web_analyticsdeals_web_analyticstickets_web_analyticsengagements_calls_web_analyticsengagements_emails_web_analyticsengagements_meetings_web_analyticsengagements_notes_web_analyticsengagements_tasks_web_analyticsgoals_web_analyticsline_items_web_analyticsproducts_web_analytics
These streams require HubSpot Marketing Hub Enterprise and the business-intelligence scope in addition to each stream's parent-object read scope (see the scopes table in Step 2). They begin syncing from the configured Start date with fresh state.
The same toggle also enables the flows stream, which syncs full workflow definitions from HubSpot's Automation v4 Flows API. See Flows vs. workflows below.
Association streams
Use Association Between Objects Streams to sync relationships between two standard HubSpot CRM objects. Add one item for each relationship you want to sync. Each item creates one stream that reads IDs from the source object, calls HubSpot's associations batch read API, and emits one record for each association.
Configure these fields for each association stream:
- From Object: The source object type, such as
tickets,deals, orcontacts. - To Object: The target object type, such as
companiesorcontacts. - Stream Name: Optional. If you leave this empty, Airbyte names the stream
associations_<from_object>_<to_object>.
For example, set From Object to tickets and To Object to companies to create the associations_tickets_companies stream. After you add or edit association stream settings, refresh the source schema so the generated streams appear in the catalog.
Association stream records include:
from_id: The ID of the source object record.to_id: The ID of the target object record.association_type_id: HubSpot's numeric association type identifier.category: The association category, such asHUBSPOT_DEFINEDorUSER_DEFINED.label: The association label. This isnullfor unlabeled associations.
Association streams sync in Full Refresh mode: the stream itself tracks no incremental cursor. Each sync reads every parent record modified since the configured start date and fetches its associations.
If you authenticate with a Private App or Service Key, grant read scopes for both selected objects. For example, a tickets-to-companies association stream needs the tickets (or, for a Service Key, crm.objects.tickets.read) and crm.objects.companies.read scopes.
Custom object association streams
Use Custom Object Association Streams to sync relationships where at least one side is a custom HubSpot object. Add one item for each relationship you want to sync.
Configure these fields for each custom object association stream:
- From Object: The source object name or identifier.
- To Object: The target object name or identifier.
- Stream Name: Optional. If you leave this empty, Airbyte names the stream
associations_<from_object>_<to_object>.
After you add or edit custom object association stream settings, refresh the source schema so the generated streams appear in the catalog.
For custom objects, use either:
- The custom object's
fullyQualifiedName, such asp_my_custom_object. - The custom object's
objectTypeId, such as2-12345.
You can use standard object names, such as contacts, companies, or deals, for the standard-object side of the relationship.
Custom object association streams emit the same fields as standard association streams: from_id, to_id, association_type_id, category, and label. Like standard association streams, they sync in Full Refresh mode.
If you authenticate with a Private App or Service Key, grant crm.objects.custom.read and the read scope for any standard object in the relationship.
Supported sync modes
The HubSpot source connector supports the following sync modes:
- Full Refresh
- Incremental
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)
Supported Streams
The HubSpot source connector supports the following streams:
- Campaigns (Client-Side Incremental)
- Companies (Incremental)
- Contact Lists (Incremental)
- Contacts (Incremental)
- Deal Pipelines (Client-Side Incremental)
- Deal Splits (Incremental)
- Deals (including Contact associations) (Incremental)
- Records that have been deleted (archived) and stored in HubSpot's recycle bin will only be kept for 90 days, see response from HubSpot Team
- 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)
- Engagements Task Pipelines (Client-Side Incremental)
- Forms (Client-Side Incremental)
- Form Submissions (Client-Side Incremental)
- Goals (Incremental)
- Leads (Incremental)
- List Memberships (Full Refresh)
- Line Items (Incremental)
- Listings (Incremental)
- Marketing Emails (Incremental)
- Owners (Client-Side Incremental)
- Owners Archived (Client-Side Incremental)
- Users (Full-Refresh)
- Products (Incremental)
- Properties (Full Refresh)
- Contacts Property History (Client-Side Incremental)
- Companies Property History (Client-Side Incremental)
- Deals Property History (Client-Side Incremental)
- Subscription Changes (Incremental)
- Tickets (Incremental)
- Ticket Pipelines (Client-Side Incremental)
- Workflows (Client-Side Incremental)
- Flows (Client-Side Incremental, experimental)
- Account Details (Full Refresh)
- Association streams for standard objects, such as
associations_tickets_companies(Full Refresh) - Custom object association streams for custom-to-standard or custom-to-custom associations (Full Refresh)
Entity-Relationship Diagram (ERD)
Flows vs. workflows
The connector exposes HubSpot automations through two independent streams. Neither replaces the other, and both can be synced at the same time.
workflows | flows | |
|---|---|---|
| HubSpot API | Legacy GET /automation/v3/workflows | GET /automation/v4/flows |
| Availability | Always available | Requires Enable experimental streams |
| Content | Inventory metadata only (name, type, enabled, counters, migration status) | Full workflow definitions |
id type | Integer | String |
| Cursor format | Epoch milliseconds | ISO 8601 date-time |
Use flows when you need the workflow definition itself rather than an inventory: the actions action graph, enrollmentCriteria, dataSources, enrollmentSchedule, timeWindows, blockedDates, goal and suppression filter branches, and un-enrollment settings.
A few things to know about the flows stream:
- It costs one extra API call per flow. The list endpoint returns summaries only, so the connector fetches
GET /automation/v4/flows/{flowId}for every flow it emits. Because filtering happens before enrichment, incremental syncs only pay this cost for flows that changed since the previous sync. - It covers more than workflows. The v4 API also returns platform flows and action sets (
flowTypeofACTION_SET), soflowstypically contains more records thanworkflows. Filter onflowTypeandtypedownstream if you only want contact workflows. - Flows are not joinable to workflows by
id. The two APIs use different identifier spaces. HubSpot exposesPOST /automation/v4/workflow-id-mappings/batch/readto translate between them; the connector does not call it. - Inaccessible flows degrade rather than fail. HubSpot requires additional
*.sensitive.readscopes for flows that reference sensitive data. If a detail request fails, the connector logs a warning naming the flow and emits its summary fields, so one restricted flow does not fail the whole stream. - The upstream API is a developer preview. HubSpot documents Automation v4 as subject to change, which is why the stream sits behind the experimental toggle. The
actions,enrollmentCriteria,dataSources, and filter-branch fields are typed as free-form objects so that new HubSpot action or criteria subtypes do not break syncs.
Notes on the property_history streams
The property history streams (contacts_property_history, companies_property_history, deals_property_history) use Client-Side Incremental sync with a cursor timestamp to determine which records have changed since the previous sync.
HubSpot calculated properties — formula fields, rollup summaries, and analytics properties such as hs_analytics_* — always have a timestamp that mirrors the time of the latest sync, not the time of the last user-initiated change. This causes the sync cursor to advance past records that have not yet been synced, which can result in missing records.
To mitigate this, configure the Property History Lookback Window in the source settings. A value of 43200 (30 days) is a reasonable starting point. Because these streams use Append + Deduped sync mode, duplicate records from the lookback period are handled automatically.
By default, these streams request history for every property on the object, which can generate many API requests and a large volume of records. To limit this, configure Deals Property History Properties, Contacts Property History Properties, or Companies Property History Properties with a list of property internal names (for example, ["dealstage"]). Only history for the listed properties is then synced for the corresponding stream. See HubSpot's default deal, contact, and company properties for the internal names. If a list is empty or not set, history for all properties is synced.
Notes on the engagements stream
- Objects in the
engagementsstream 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 theengagements_metadatatable in the destination:
- A
callengagement has a correspondingengagements_metadataobject with non-null values in thetoNumber,fromNumber,status,externalId,durationMilliseconds,externalAccountId,recordingUrl,body, anddispositioncolumns. - An
emailengagement has a correspondingengagements_metadataobject with non-null values in thesubject,html, andtextcolumns. In addition, there will be records in four related tables,engagements_metadata_from,engagements_metadata_to,engagements_metadata_cc,engagements_metadata_bcc. - A
meetingengagement has a correspondingengagements_metadataobject with non-null values in thebody,startTime,endTime, andtitlecolumns. - A
noteengagement has a correspondingengagements_metadataobject with non-null values in thebodycolumn. - A
taskengagement has a correspondingengagements_metadataobject with non-null values in thebody,status, andforObjectTypecolumns.
- The
engagementsstream uses two different APIs based on the length of time since the last sync and the number of records which Airbyte 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. To accommodate for this limitation, we recommend scheduling more frequent syncs.
Notes on the deal_pipelines stream
Starting with version 6.13.3, the deal_pipelines stream reads from HubSpot's Pipelines API 2026-09, because HubSpot retires Pipelines API V1 on December 4, 2026. The connector converts the records back to the V1 shape, so columns, the primary key and the cursor stay the same. A few details of the output differ from earlier versions:
- The new API doesn't return
default. The connector sets it totruewhenpipelineIdisdefault, which is HubSpot's built-in deal pipeline, and tofalsefor every other pipeline. - The new API doesn't return
objectTypeorobjectTypeId. The connector sets them toDEALand0-3, the values V1 returned for deal pipelines. - Each item in
stageshas a newwritePermissionsfield. - Stages of the built-in pipeline can have
updatedAtset to0instead ofnull. - Stages within a pipeline can be listed in a different order.
Notes on the Forms and Form Submissions stream
This stream only syncs marketing forms.
Notes on the list_memberships stream
The list_memberships stream reads memberships for every list returned by the contact_lists stream by calling HubSpot's GET /crm/v3/lists/{listId}/memberships endpoint. A few behaviors are worth knowing about:
- The stream only supports full refresh. HubSpot's memberships endpoint doesn't expose a cursor suitable for incremental sync.
- Records are keyed by the composite primary key
(recordId, listId).listIdis emitted as a string so records serialize cleanly to Avro destinations. - Some lists returned by
contact_listsreference anobjectTypeIdthat isn't active for your portal (for example, Leads lists withobjectTypeId0-136). HubSpot's memberships endpoint rejects those lists with a 400VALIDATION_ERROR / ListError.INVALID_OBJECT_TYPE_FOR_LIST. The connector skips those lists so they don't fail the sync, and logs an entry for each one. If you need memberships for those object types, enable the corresponding object in HubSpot or sync the object directly from its own stream (for example,leads).
Notes on the Custom CRM Objects
Custom CRM Objects will appear as streams available for sync, alongside the standard objects listed above.
If a custom object has the same name as a built-in stream (for example, a custom object named form_submissions), discover returns two streams with that name and connection setup fails with a duplicate stream name error. To fix this, enable Prefix custom objects that share a name with a built-in stream (prefix_colliding_custom_objects) in the source configuration and refresh the source schema. The custom object is then exposed as custom_object_<name>. Custom objects with other names are not renamed. If you were already syncing the built-in stream with that name, it may have been receiving the custom object's records. After enabling the setting and refreshing the schema, clear that stream's data so its destination table contains only the built-in stream's records.
If you set up your connections before April 15th, 2023 (on Airbyte Cloud) or before 0.8.0 (OSS) then you'll need to do some additional work to sync custom CRM objects.
First you need to give the connector some additional permissions:
-
If you are using OAuth on Airbyte Cloud go to the HubSpot source settings page in the Airbyte UI and re-authenticate via OAuth to allow Airbyte the permissions to access custom objects.
-
If you are using OAuth on OSS, Private App, or Service Key auth go into the HubSpot UI where you created your Private App, Service Key, or OAuth application and add the
crm.objects.custom.readscope to its scopes. See HubSpot's scopes documentation.
Then, go to the schema tab of your connection and click refresh source schema to pull in those new streams for syncing.
Limitations & Troubleshooting
Expand to see details about HubSpot connector limitations and troubleshooting.
Rate limiting
The connector is restricted by normal HubSpot rate limits. The burst limit applies per app, and the daily limit is shared across all apps within the same HubSpot account.
| Product tier | Burst (per 10 seconds) | Daily (per account) |
|---|---|---|
| Free & Starter | 100 | 250,000 |
| Professional | 190 | 625,000 |
| Enterprise | 190 | 1,000,000 |
| API Limit Increase add-on | 250 | +1,000,000 per add-on (max 2) |
Custom properties sync slowly
If you use custom properties in HubSpot, syncs take longer. Airbyte doesn't alert you to the presence of custom properties, but you can check if you're using them with HubSpot's UI.
Troubleshooting
-
Enabling streams: Some streams, such as
workflows, require specific scopes before they can be read. If the authenticated user does not have the necessary permissions, the connector logs a warning and skips the stream. -
HubSpot object labels In HubSpot, a label can be applied to a stream that differs from the original API name of the stream. HubSpot's UI shows the label of the stream, whereas Airbyte shows the name of the stream. If you are having issues seeing a particular stream your user should have access to, search for the
nameof the HubSpot object instead. -
Unnesting top level properties: Since version 1.5.0, in order to offer users access to nested fields, we also denest the top-level fields into individual fields in the destination. This is most commonly observed in the
propertiesfield, which is now split into each attribute in the destination.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"} -
401 Unauthorized Error (Private App Token or Service Key)
If you authenticate using a Private App access token or a Service Key and receive a 401 Unauthorized error, the connector fails immediately with a configuration error asking you to update your token. These tokens are static and cannot be refreshed, so retrying won't help. To resolve this, generate a new access token in your HubSpot Private App settings or rotate your Service Key and update the connector configuration.
If you authenticate using OAuth, the connector automatically refreshes expired tokens and retries the request. No action is needed unless the error persists, in which case you should re-authenticate the connector.
-
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.
-
Additional permissions:
feedback_submissions: Service Hub Professional accountmarketing_emails: Market Hub Starter accountworkflows: Sales, Service, and Marketing Hub Professional accountsflows: Sales, Service, and Marketing Hub Professional accounts
-
-
Check out common troubleshooting issues for the HubSpot source connector on our Airbyte Forum.
-
Missing records in CRM Search streams (
deals,companies,engagements_calls,engagements_emails,engagements_meetings,engagements_notes,engagements_tasks,contacts,deal_splits,leads,tickets):- If you notice missing records during incremental syncs, it may be due to irregularities in HubSpot's API behavior.
- To mitigate this, configure the CRM Search Lookback Window in the source settings. This re-fetches data for a specified number of minutes before the state from the previous sync, helping to capture missing records.
contactsand custom objects read their first incremental sync (and any sync after a reset or refresh) from the list endpoint instead of CRM Search. That sync can save a cursor later than the time it started. A record that was already read and was then edited before the sync finished is not picked up by the next sync. Set the CRM Search Lookback Window to at least the duration of that first sync, in minutes. With Incremental | Append + Deduped, the records fetched again are deduplicated.
-
Missing records in property history streams (
deals_property_history,contacts_property_history,companies_property_history):- HubSpot calculated properties (formula fields, rollup summaries, analytics properties) can emit timestamps ahead of user-initiated changes, causing the sync cursor to advance past records that have not yet been synced.
- To mitigate this, configure the Property History Lookback Window in the source settings. A value of
43200(30 days) is recommended. Since these streams use Append + Deduped sync mode, duplicate records from the lookback period are handled automatically.
-
Destination type conversion errors on dynamic
number/booleanproperties (for example,JSON → NUMERIC,JSON → BOOL, or decimal-precision / scale errors on fields likehs_hd_ticket_ids,zendesk_requester_id,hs_task_send_default_reminder, or anycompanies.properties.*field):- HubSpot sometimes declares a property as
numberorbooleanbut returns values that cannot be cast to that type — for example, semicolon-separated IDs ("3092727991;3881228353;15895321999") in anumberfield, multi-value text in abooleanfield, or numbers beyond the declared precision. When that happens the connector emits the raw string, but because the published schema still saysnumber/boolean, strict destinations reject the record. - To resolve this, enable Treat dynamic number and boolean properties as strings (
treat_numbers_and_booleans_as_strings) in the source configuration. When this option is on, the connector declares every HubSpot dynamic property that would otherwise benumberorbooleanasstring, so the affected values land in the destination as strings rather than failing type conversion. - The toggle only affects HubSpot dynamic
properties.*fields. Static schema fields and non-property fields are not changed. - After enabling the toggle you must refresh both the schema and the data, otherwise the new string type will not reach the destination. In the Airbyte UI:
- Open the affected connection.
- Click Refresh source schema and save the updated catalog — the affected columns should now be
string. - Trigger a Refresh data sync (or clear the affected streams and run a new sync) so the destination tables are rewritten with the new column type and previously-rejected records are re-emitted as strings.
- The same steps apply if you later disable the toggle — refresh the schema and the data so the destination column types match the new catalog.
- HubSpot sometimes declares a property as
IP allow list
If you use Airbyte Cloud and your organization restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.
Reference
Config fields reference
Changelog
To see this connector's version history, read the HubSpot changelog. For older versions, see versions 0.x–4.x.