or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

api-client.mdbase-stream-classes.mdcrm-streams.mdcustom-objects.mdengagement-streams.mderror-handling.mdindex.mdmarketing-sales-streams.mdproperty-history-streams.mdsource-connector.mdweb-analytics.md
tile.json

tessl/pypi-airbyte-source-hubspot

Airbyte source connector for HubSpot that enables data synchronization from HubSpot's CRM and marketing platform to various destinations.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/source-hubspot@6.44.x

To install, run

npx @tessl/cli install tessl/pypi-airbyte-source-hubspot@6.44.0

index.mddocs/

Airbyte Source HubSpot

An Airbyte source connector for HubSpot that enables comprehensive data synchronization from HubSpot's CRM and marketing platform to various destinations. Built using Airbyte's low-code Declarative Source framework, this connector supports multiple data streams including contacts, companies, deals, tickets, engagements, marketing emails, forms, workflows, and custom CRM objects.

Package Information

  • Package Name: source-hubspot
  • Package Type: Python package (Airbyte connector)
  • Language: Python (^3.10,<3.12)
  • Package Manager: Poetry
  • License: ELv2 (Elastic License 2.0)
  • Installation: Available as part of Airbyte platform
  • Documentation: https://docs.airbyte.com/integrations/sources/hubspot

Core Imports

from source_hubspot import SourceHubspot
from source_hubspot.run import run

For direct stream access:

from source_hubspot.streams import (
    API, Contacts, Companies, Deals, Tickets, Leads, DealSplits,
    EngagementsCalls, EngagementsEmails, Forms, Goals, LineItems,
    Products, FeedbackSubmissions, CustomObject, WebAnalyticsStream
)

Basic Usage

from source_hubspot import SourceHubspot
from airbyte_cdk.models import ConfiguredAirbyteCatalog

# OAuth configuration
config = {
    "credentials": {
        "credentials_title": "OAuth Credentials",
        "client_id": "your_client_id",
        "client_secret": "your_client_secret",
        "refresh_token": "your_refresh_token"
    },
    "start_date": "2023-01-01T00:00:00Z"
}

# Create source instance
source = SourceHubspot(catalog=None, config=config, state=None)

# Check connection
is_healthy, error = source.check_connection(logger, config)

# Get available streams
streams = source.streams(config)

Architecture

The HubSpot source connector is built on Airbyte's Declarative Source framework with several key components:

  • SourceHubspot: Main connector class extending YamlDeclarativeSource
  • API: HTTP client handling authentication and HubSpot API communication
  • Stream Classes: Individual classes for each data type (Contacts, Companies, etc.)
  • Authentication: Support for both OAuth 2.0 and Private App credentials
  • Error Handling: Comprehensive error handling for rate limits, timeouts, and permissions
  • Scope Management: Dynamic stream availability based on granted OAuth scopes

The connector uses a manifest.yaml file for declarative configuration and supports both incremental and full refresh sync modes with sophisticated rate limiting and retry mechanisms.

Capabilities

Source Connector

Primary source connector functionality for creating and managing the HubSpot data integration, including connection checking, stream discovery, and authentication scope validation.

class SourceHubspot(YamlDeclarativeSource):
    def __init__(catalog: Optional[ConfiguredAirbyteCatalog], config: Optional[Mapping[str, Any]], state: TState, **kwargs): ...
    def check_connection(logger: logging.Logger, config: Mapping[str, Any]) -> Tuple[bool, Optional[Any]]: ...
    def streams(config: Mapping[str, Any]) -> List[Stream]: ...

Source Connector

API Client

HTTP client for HubSpot API communication with authentication, error handling, and custom object metadata discovery.

class API:
    def __init__(credentials: Mapping[str, Any]): ...
    def get(url: str, params: MutableMapping[str, Any] = None) -> Tuple[Union[MutableMapping[str, Any], List[MutableMapping[str, Any]]], requests.Response]: ...
    def post(url: str, data: Mapping[str, Any], params: MutableMapping[str, Any] = None) -> Tuple[Union[Mapping[str, Any], List[Mapping[str, Any]]], requests.Response]: ...
    def get_custom_objects_metadata() -> Iterable[Tuple[str, str, Mapping[str, Any]]]: ...

API Client

CRM Data Streams

Stream classes for core HubSpot CRM objects including contacts, companies, deals, tickets, leads, and deal splits with incremental sync capabilities.

class Contacts(CRMSearchStream): ...
class Companies(CRMSearchStream): ...
class Deals(CRMSearchStream): ...
class Tickets(CRMSearchStream): ...
class Leads(CRMSearchStream): ...
class DealSplits(CRMSearchStream): ...

CRM Data Streams

Engagement Streams

Stream classes for HubSpot engagement data including calls, emails, meetings, notes, and tasks.

class EngagementsCalls(CRMSearchStream): ...
class EngagementsEmails(CRMSearchStream): ...
class EngagementsMeetings(CRMSearchStream): ...
class EngagementsNotes(CRMSearchStream): ...
class EngagementsTasks(CRMSearchStream): ...

Engagement Streams

Marketing & Sales Streams

Stream classes for marketing and sales data including forms, form submissions, owners, products, goals, line items, and feedback submissions.

class Forms(ClientSideIncrementalStream): ...
class FormSubmissions(ClientSideIncrementalStream): ...
class Owners(ClientSideIncrementalStream): ...
class Products(CRMObjectIncrementalStream): ...
class Goals(CRMObjectIncrementalStream): ...
class LineItems(CRMObjectIncrementalStream): ...
class FeedbackSubmissions(CRMObjectIncrementalStream): ...

Marketing & Sales Streams

Custom Objects

Support for HubSpot custom objects with dynamic schema generation and custom properties handling.

class CustomObject(CRMSearchStream, ABC):
    def __init__(entity: str, schema: Mapping[str, Any], fully_qualified_name: str, custom_properties: Mapping[str, Any], **kwargs): ...

Custom Objects

Web Analytics (Experimental)

Experimental web analytics streams providing engagement analytics data for various HubSpot objects.

class WebAnalyticsStream(HttpSubStream, BaseStream): ...
class ContactsWebAnalytics(WebAnalyticsStream): ...
class CompaniesWebAnalytics(WebAnalyticsStream): ...

Web Analytics

Error Handling

Comprehensive error handling classes for HubSpot API-specific errors including authentication, rate limiting, and timeouts.

class HubspotError(AirbyteTracedException): ...
class HubspotInvalidAuth(HubspotError): ...
class HubspotRateLimited(HTTPError): ...
class HubspotTimeout(HTTPError): ...

Error Handling

Property History Streams

Specialized streams for tracking changes to CRM object properties over time.

class CompaniesPropertyHistory(IncrementalStream): ...
class ContactsPropertyHistory(IncrementalStream): ...
class DealsPropertyHistory(IncrementalStream): ...

Property History Streams

Base Stream Classes

Foundation classes for extending and customizing HubSpot stream functionality.

class BaseStream(HttpStream, ABC): ...
class IncrementalStream(BaseStream, ABC): ...
class CRMSearchStream(IncrementalStream, ABC): ...
class CRMObjectStream(BaseStream): ...
class CRMObjectIncrementalStream(CRMObjectStream, IncrementalStream): ...
class ClientSideIncrementalStream(BaseStream, CheckpointMixin): ...

Base Stream Classes

Configuration

Authentication Types

  • OAuth Credentials: Standard OAuth 2.0 flow with client credentials and refresh token
  • Private App Credentials: Direct API access using private app access token

Configuration Parameters

  • start_date: ISO 8601 datetime string (defaults to "2006-06-01T00:00:00Z")
  • enable_experimental_streams: Boolean flag to enable web analytics streams
  • num_worker: Integer for concurrent workers (1-40, default 3)

Types

# Configuration types
Mapping[str, Any]  # Configuration object
List[Stream]      # Stream collection
Tuple[bool, Optional[Any]]  # Check connection result

# Authentication credential types
class OAuthCredentials:
    credentials_title: str = "OAuth Credentials"
    client_id: str
    client_secret: str
    refresh_token: str

class PrivateAppCredentials:  
    credentials_title: str = "Private App Credentials"
    access_token: str