0
# Airbyte Source HubSpot
1

2
A manifest-only declarative source connector for Airbyte that enables comprehensive data synchronization from HubSpot CRM to data warehouses and other destinations. The connector supports both OAuth and Private App authentication methods and provides access to 30+ data streams including contacts, companies, deals, marketing activities, and engagement data.
3

4
## Package Information
5

6
- **Package Name**: source-hubspot
7
- **Package Type**: airbyte
8
- **Language**: YAML (declarative manifest)
9
- **Installation**: Available in Airbyte Cloud and Open Source as connector `source-hubspot` version `6.0.0`
10

11
## Core Configuration
12

13
```yaml
14
source-type: airbyte/source-hubspot
15
config:
16
  credentials:
17
    credentials_title: "OAuth Credentials"  # or "Private App Credentials"
18
    # OAuth credentials
19
    client_id: "${HUBSPOT_CLIENT_ID}"
20
    client_secret: "${HUBSPOT_CLIENT_SECRET}"
21
    refresh_token: "${HUBSPOT_REFRESH_TOKEN}"
22
    # OR Private App credentials
23
    access_token: "${HUBSPOT_ACCESS_TOKEN}"
24
  start_date: "2023-01-01T00:00:00Z"
25
```
26

27
## Basic Usage
28

29
```yaml
30
source:
31
  type: airbyte/source-hubspot
32
  config:
33
    credentials:
34
      credentials_title: "Private App Credentials"
35
      access_token: "${HUBSPOT_ACCESS_TOKEN}"
36
    start_date: "2023-01-01T00:00:00Z"
37
    
38
destination:
39
  type: airbyte/destination-postgres
40
  config:
41
    # destination configuration
42
```
43

44
## Architecture
45

46
The HubSpot source connector is built on Airbyte's declarative manifest framework:
47

48
- **Manifest-Driven**: Configuration-based connector using YAML manifest instead of custom Python code
49
- **Authentication Layer**: Selective authentication supporting both OAuth 2.0 and Private App tokens
50
- **Stream Definitions**: 30+ predefined streams with incremental sync and pagination support
51
- **Custom Components**: Specialized Python components for complex data transformations and API interactions
52
- **Dynamic Schemas**: Runtime schema discovery for custom properties and objects
53
- **Rate Limiting**: Built-in rate limiting and retry logic for HubSpot's API constraints
54

55
## Capabilities
56

57
### Authentication & Configuration
58

59
Flexible authentication system supporting OAuth 2.0 flows and Private App tokens, with comprehensive configuration options for data synchronization behavior.
60

61
```yaml { .api }
62
credentials:
63
  type: object
64
  oneOf:
65
    - type: object  # OAuth Credentials
66
      properties:
67
        credentials_title:
68
          const: "OAuth Credentials"
69
        client_id: string
70
        client_secret: string
71
        refresh_token: string
72
    - type: object  # Private App Credentials
73
      properties:
74
        credentials_title:
75
          const: "Private App Credentials"
76
        access_token: string
77

78
start_date:
79
  type: string
80
  format: date-time
81
  pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
82
  default: "2006-06-01T00:00:00Z"
83

84
enable_experimental_streams:
85
  type: boolean
86
  default: false
87

88
num_worker:
89
  type: integer
90
  minimum: 1
91
  maximum: 40
92
  default: 3
93
  description: "Number of concurrent workers for data synchronization"
94

95
lookback_window:
96
  type: integer
97
  default: 0
98
  description: "Number of days to look back from cursor position for incremental sync"
99
```
100

101
[Authentication & Configuration](./authentication.md)
102

103
### CRM Data Streams
104

105
Core customer relationship management data including contacts, companies, deals, and their relationships with full incremental sync support.
106

107
```yaml { .api }
108
# Core entity streams
109
contacts:
110
  primary_key: ["id"]
111
  cursor_field: "updatedAt"
112
  sync_mode: incremental
113

114
companies: 
115
  primary_key: ["id"]
116
  cursor_field: "updatedAt"
117
  sync_mode: incremental
118

119
deals:
120
  primary_key: ["id"] 
121
  cursor_field: "updatedAt"
122
  sync_mode: incremental
123

124
tickets:
125
  primary_key: ["id"]
126
  cursor_field: "updatedAt"
127
  sync_mode: incremental
128

129
goals:
130
  primary_key: ["id"]
131
  cursor_field: "updatedAt"
132
  sync_mode: incremental
133

134
leads:
135
  primary_key: ["id"]
136
  cursor_field: "updatedAt"
137
  sync_mode: incremental
138

139
contact_lists:
140
  primary_key: ["id"]
141
  cursor_field: "updatedAt"
142
  sync_mode: incremental
143

144
deal_splits:
145
  primary_key: ["id"]
146
  cursor_field: "updatedAt"
147
  sync_mode: incremental
148
```
149

150
[CRM Streams](./crm-streams.md)
151

152
### Property History Streams
153

154
Historical tracking of property changes for CRM entities, providing audit trails and change tracking capabilities.
155

156
```yaml { .api }
157
contacts_property_history:
158
  primary_key: ["contactId", "property", "timestamp"]
159
  cursor_field: "timestamp"
160
  sync_mode: incremental
161

162
companies_property_history:
163
  primary_key: ["companyId", "property", "timestamp"] 
164
  cursor_field: "timestamp"
165
  sync_mode: incremental
166

167
deals_property_history:
168
  primary_key: ["objectId", "property", "timestamp"]
169
  cursor_field: "timestamp" 
170
  sync_mode: incremental
171
```
172

173
[Property History](./property-history.md)
174

175
### Engagement Streams
176

177
Activity and interaction data including calls, emails, meetings, notes, and tasks with associations to CRM entities.
178

179
```yaml { .api }
180
engagements_calls:
181
  primary_key: ["id"]
182
  cursor_field: "updatedAt"
183
  sync_mode: incremental
184

185
engagements_emails:
186
  primary_key: ["id"]
187
  cursor_field: "updatedAt" 
188
  sync_mode: incremental
189

190
engagements_meetings:
191
  primary_key: ["id"]
192
  cursor_field: "updatedAt"
193
  sync_mode: incremental
194

195
engagements_notes:
196
  primary_key: ["id"]
197
  cursor_field: "updatedAt"
198
  sync_mode: incremental
199

200
engagements_tasks:
201
  primary_key: ["id"]
202
  cursor_field: "updatedAt"
203
  sync_mode: incremental
204
```
205

206
[Engagement Streams](./engagements.md)
207

208
### Marketing Streams
209

210
Marketing automation data including campaigns, emails, forms, workflows, and email events for comprehensive marketing analytics.
211

212
```yaml { .api }
213
marketing_emails:
214
  primary_key: ["id"]
215
  cursor_field: "updatedAt"
216
  sync_mode: incremental
217

218
campaigns:
219
  primary_key: ["id"] 
220
  cursor_field: "lastUpdatedTime"
221
  sync_mode: incremental
222

223
email_events:
224
  primary_key: ["id"]
225
  cursor_field: "created"
226
  sync_mode: incremental
227

228
forms:
229
  primary_key: ["id"]
230
  cursor_field: "updatedAt"
231
  sync_mode: incremental
232

233
workflows:
234
  primary_key: ["id"]
235
  cursor_field: "updatedAt"
236
  sync_mode: incremental
237
```
238

239
[Marketing Streams](./marketing.md)
240

241
### Custom Objects & Dynamic Schemas
242

243
Support for HubSpot custom objects with runtime schema discovery and automatic property mapping.
244

245
```yaml { .api }
246
dynamic_streams:
247
  - type: DynamicDeclarativeStream
248
    stream_template:
249
      type: StateDelegatingStream
250
      name: "custom_object_stream_name"  # Generated dynamically
251
    components_resolver:
252
      type: HttpComponentsResolver
253
      retriever:
254
        path: "/crm/v3/schemas"
255
```
256

257
[Custom Objects](./custom-objects.md)
258

259
### Additional Streams
260

261
Supplementary data streams including form submissions, archived owners, and pipeline configurations for comprehensive data coverage.
262

263
```yaml { .api }
264
form_submissions:
265
  primary_key: ["id"]
266
  cursor_field: "submittedAt"
267
  sync_mode: incremental
268

269
owners_archived:
270
  primary_key: ["id"]
271
  cursor_field: "updatedAt"
272
  sync_mode: incremental
273

274
ticket_pipelines:
275
  primary_key: ["id"]
276
  cursor_field: "updatedAt"
277
  sync_mode: incremental
278
```
279

280
[Additional Streams](./additional-streams.md)
281

282
## Types
283

284
### Authentication Types
285

286
```yaml { .api }
287
OAuthCredentials:
288
  type: object
289
  properties:
290
    credentials_title:
291
      type: string
292
      const: "OAuth Credentials"
293
    client_id:
294
      type: string
295
      description: "HubSpot application client ID"
296
    client_secret:
297
      type: string
298
      description: "HubSpot application client secret"
299
    refresh_token:
300
      type: string
301
      description: "OAuth refresh token for token renewal"
302

303
PrivateAppCredentials:
304
  type: object
305
  properties:
306
    credentials_title:
307
      type: string
308
      const: "Private App Credentials"
309
    access_token:
310
      type: string
311
      description: "HubSpot Private App access token"
312
```
313

314
### Common Stream Properties
315

316
```yaml { .api }
317
StreamConfig:
318
  type: object
319
  properties:
320
    primary_key:
321
      type: array
322
      items:
323
        type: string
324
      description: "Fields that uniquely identify records"
325
    cursor_field:
326
      type: string
327
      description: "Field used for incremental sync"
328
    sync_mode:
329
      type: string
330
      enum: ["full_refresh", "incremental"]
331
      description: "Synchronization mode"
332

333
IncrementalSync:
334
  type: object
335
  properties:
336
    cursor_field:
337
      type: string
338
    start_datetime:
339
      type: string
340
      format: date-time
341
    datetime_format:
342
      type: string
343
    lookback_window:
344
      type: string
345
      pattern: "^P\\d+D$"
346
```