dockerRepository: airbyte/destination-hubspot
HubSpot destination
Set up the HubSpot destination connector by following this guide. The connector supports data activation for operational workflows.
Prerequisites
- A HubSpot account
- Airbyte version 1.8 or later, or Airbyte Cloud
S3 prerequisites for rejected records
If you use an S3 bucket to store rejected records, you’ll also need the following.
-
Allow connections between Airbyte and your AWS S3/Minio S3 cluster if they’re in separate VPCs.
-
An S3 bucket with credentials, a Role ARN, or an instance profile with host read/write permissions configured for EC2 or EKS.
-
These fields are always required:
- S3 Bucket Name
- S3 Bucket Region
- Prefix Path in the Bucket
-
If you use STS Assume Role, you must provide:
- Role ARN
-
If you use AWS credentials, you must provide:
- Access Key ID
- Secret Access Key
-
If you use an Instance Profile, you can omit the Access Key ID, Secret Access Key, and Role ARN.
-
Setup guide
Set up HubSpot in Airbyte
-
Log in to your Airbyte account.
-
Select Destination, then select + New destination.
-
On the Set up the destination page, select HubSpot from the Destination tiles.
-
Enter a name for the HubSpot connector.
-
OAuth authentication is available from the Authentication dropdown. Select Authenticate your HubSpot account to sign in with HubSpot and authorise your account.
:::note HubSpot authentication issues The popup window may display the error
An invalid scope name was providedduring authentication. Close the window and retry authentication. ::: -
Select Set up destination and wait for the tests to finish.
Supported sync modes
| Sync mode | Supported? |
|---|---|
| Full Refresh - Overwrite | No |
| Full Refresh - Append | Yes |
| Full Refresh - Overwrite + Deduped | No |
| Incremental Sync - Append | Yes |
| Incremental Sync - Append + Deduped | No |
This is a data activation destination. Alongside the Airbyte sync modes above, HubSpot supports per-object write operations: insert, upsert, update, and soft delete. Configure these operations in the connection settings.
Supported objects
The HubSpot destination connector supports these streams:
- Companies: Upsert on unique field
- Contacts: Upsert on email
- Deals: Upsert on unique field
- Products: Upsert on unique field
- Custom Objects: Upsert on unique field
Limitations and troubleshooting
Rate limits
The connector automatically follows HubSpot’s standard API rate limits. If rate limiting occurs, the connector retries requests with exponential backoff.
Missing destination objects
For every object except CONTACT, which uses email as its matching key, upsert requires a unique value field on the destination object.
Matching Key Requirements:
- CONTACT: Uses email field automatically
- All other objects: Requires a property with unique values enabled
Create a unique value property in HubSpot:
- From the CRM menu on the left, select the object you want to sync
- Under
Actions, selectEdit Properties - Select
Create property - When entering the rules, select
Require unique values for this property
App verification
HubSpot requires application usage, such as more than 60 installations, before verifying the HubSpot application. During installation, you might see “You’re connecting to an unverified app”. This warning is expected for the first users. Once the application receives enough traffic, it can be verified and the warning will disappear.
Scopes for unsupported streams
During app installation, you might see scopes for unsupported objects. This is expected because changing scopes might require users to re-authenticate, which can be disruptive. To avoid this, scopes were added for objects intended for future support based on user demand.
403 Forbidden error
Hubspot has scopes for each API call. Each stream is linked to a scope and requires access to sync data. Review the Hubspot OAuth scope documentation here.
Namespace support
This destination doesn’t support namespaces.
Changelog
Expand to review
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 0.0.13 | 2026-11-10 | 91834 | Fix HubSpot OAuth authorization by sending the PKCE code_challenge_method and code_verifier |
| 0.0.12 | 2026-06-17 | 80214 | Move to community support level |
| 0.0.11 | 2026-04-15 | 76336 | Upgrade Bulk CDK to 1.0.8 (OAuth token expiry fix) |
| 0.0.10 | 2026-02-09 | 72975 | Upgrade CDK to 1.0.1 |
| 0.0.9 | 2026-01-26 | 72304 | Upgrade CDK to 0.2.0 |
| 0.0.8 | 2025-11-05 | 69131 | Upgrade to Bulk CDK 0.1.61. |
| 0.0.7 | 2025-09-24 | 66684 | Pin to CDK artifact |
| 0.0.6 | 2025-09-10 | 65986 | Adding product object |
| 0.0.5 | 2025-09-08 | 65157 | Update following breaking changes on spec |
| 0.0.4 | 2025-07-31 | 64144 | OSS release |
| 0.0.3 | 2025-07-18 | 205 | Forcing new release |
| 0.0.2 | 2025-07-18 | 204 | Fixing auth |
| 0.0.1 | 2025-07-18 | 201 | First iteration internally |