0
# Airbyte Source HubSpot
1

2
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.
3

4
## Package Information
5

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

14
## Core Imports
15

16
```python
17
from source_hubspot import SourceHubspot
18
from source_hubspot.run import run
19
```
20

21
For direct stream access:
22

23
```python
24
from source_hubspot.streams import (
25
    API, Contacts, Companies, Deals, Tickets, Leads, DealSplits,
26
    EngagementsCalls, EngagementsEmails, Forms, Goals, LineItems,
27
    Products, FeedbackSubmissions, CustomObject, WebAnalyticsStream
28
)
29
```
30

31
## Basic Usage
32

33
```python
34
from source_hubspot import SourceHubspot
35
from airbyte_cdk.models import ConfiguredAirbyteCatalog
36

37
# OAuth configuration
38
config = {
39
    "credentials": {
40
        "credentials_title": "OAuth Credentials",
41
        "client_id": "your_client_id",
42
        "client_secret": "your_client_secret",
43
        "refresh_token": "your_refresh_token"
44
    },
45
    "start_date": "2023-01-01T00:00:00Z"
46
}
47

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

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

54
# Get available streams
55
streams = source.streams(config)
56
```
57

58
## Architecture
59

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

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

69
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.
70

71
## Capabilities
72

73
### Source Connector
74

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

77
```python { .api }
78
class SourceHubspot(YamlDeclarativeSource):
79
    def __init__(catalog: Optional[ConfiguredAirbyteCatalog], config: Optional[Mapping[str, Any]], state: TState, **kwargs): ...
80
    def check_connection(logger: logging.Logger, config: Mapping[str, Any]) -> Tuple[bool, Optional[Any]]: ...
81
    def streams(config: Mapping[str, Any]) -> List[Stream]: ...
82
```
83

84
[Source Connector](./source-connector.md)
85

86
### API Client
87

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

90
```python { .api }
91
class API:
92
    def __init__(credentials: Mapping[str, Any]): ...
93
    def get(url: str, params: MutableMapping[str, Any] = None) -> Tuple[Union[MutableMapping[str, Any], List[MutableMapping[str, Any]]], requests.Response]: ...
94
    def post(url: str, data: Mapping[str, Any], params: MutableMapping[str, Any] = None) -> Tuple[Union[Mapping[str, Any], List[Mapping[str, Any]]], requests.Response]: ...
95
    def get_custom_objects_metadata() -> Iterable[Tuple[str, str, Mapping[str, Any]]]: ...
96
```
97

98
[API Client](./api-client.md)
99

100
### CRM Data Streams
101

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

104
```python { .api }
105
class Contacts(CRMSearchStream): ...
106
class Companies(CRMSearchStream): ...
107
class Deals(CRMSearchStream): ...
108
class Tickets(CRMSearchStream): ...
109
class Leads(CRMSearchStream): ...
110
class DealSplits(CRMSearchStream): ...
111
```
112

113
[CRM Data Streams](./crm-streams.md)
114

115
### Engagement Streams
116

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

119
```python { .api }
120
class EngagementsCalls(CRMSearchStream): ...
121
class EngagementsEmails(CRMSearchStream): ...
122
class EngagementsMeetings(CRMSearchStream): ...
123
class EngagementsNotes(CRMSearchStream): ...
124
class EngagementsTasks(CRMSearchStream): ...
125
```
126

127
[Engagement Streams](./engagement-streams.md)
128

129
### Marketing & Sales Streams
130

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

133
```python { .api }
134
class Forms(ClientSideIncrementalStream): ...
135
class FormSubmissions(ClientSideIncrementalStream): ...
136
class Owners(ClientSideIncrementalStream): ...
137
class Products(CRMObjectIncrementalStream): ...
138
class Goals(CRMObjectIncrementalStream): ...
139
class LineItems(CRMObjectIncrementalStream): ...
140
class FeedbackSubmissions(CRMObjectIncrementalStream): ...
141
```
142

143
[Marketing & Sales Streams](./marketing-sales-streams.md)
144

145
### Custom Objects
146

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

149
```python { .api }
150
class CustomObject(CRMSearchStream, ABC):
151
    def __init__(entity: str, schema: Mapping[str, Any], fully_qualified_name: str, custom_properties: Mapping[str, Any], **kwargs): ...
152
```
153

154
[Custom Objects](./custom-objects.md)
155

156
### Web Analytics (Experimental)
157

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

160
```python { .api }
161
class WebAnalyticsStream(HttpSubStream, BaseStream): ...
162
class ContactsWebAnalytics(WebAnalyticsStream): ...
163
class CompaniesWebAnalytics(WebAnalyticsStream): ...
164
```
165

166
[Web Analytics](./web-analytics.md)
167

168
### Error Handling
169

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

172
```python { .api }
173
class HubspotError(AirbyteTracedException): ...
174
class HubspotInvalidAuth(HubspotError): ...
175
class HubspotRateLimited(HTTPError): ...
176
class HubspotTimeout(HTTPError): ...
177
```
178

179
[Error Handling](./error-handling.md)
180

181
### Property History Streams
182

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

185
```python { .api }
186
class CompaniesPropertyHistory(IncrementalStream): ...
187
class ContactsPropertyHistory(IncrementalStream): ...
188
class DealsPropertyHistory(IncrementalStream): ...
189
```
190

191
[Property History Streams](./property-history-streams.md)
192

193
### Base Stream Classes
194

195
Foundation classes for extending and customizing HubSpot stream functionality.
196

197
```python { .api }
198
class BaseStream(HttpStream, ABC): ...
199
class IncrementalStream(BaseStream, ABC): ...
200
class CRMSearchStream(IncrementalStream, ABC): ...
201
class CRMObjectStream(BaseStream): ...
202
class CRMObjectIncrementalStream(CRMObjectStream, IncrementalStream): ...
203
class ClientSideIncrementalStream(BaseStream, CheckpointMixin): ...
204
```
205

206
[Base Stream Classes](./base-stream-classes.md)
207

208
## Configuration
209

210
### Authentication Types
211

212
- **OAuth Credentials**: Standard OAuth 2.0 flow with client credentials and refresh token
213
- **Private App Credentials**: Direct API access using private app access token
214

215
### Configuration Parameters
216

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

221
## Types
222

223
```python { .api }
224
# Configuration types
225
Mapping[str, Any]  # Configuration object
226
List[Stream]      # Stream collection
227
Tuple[bool, Optional[Any]]  # Check connection result
228

229
# Authentication credential types
230
class OAuthCredentials:
231
    credentials_title: str = "OAuth Credentials"
232
    client_id: str
233
    client_secret: str
234
    refresh_token: str
235

236
class PrivateAppCredentials:  
237
    credentials_title: str = "Private App Credentials"
238
    access_token: str
239
```