CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/airbyte-airbyte-source-hubspot

HubSpot source connector for Airbyte that syncs CRM data including contacts, companies, deals, and marketing activities with support for OAuth and Private App authentication

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

authentication.mddocs/

Authentication & Configuration

Authentication and configuration system for the HubSpot source connector, supporting multiple authentication methods and comprehensive synchronization options.

Capabilities

OAuth Authentication

OAuth 2.0 authentication flow for accessing HubSpot APIs with user-delegated permissions.

credentials:
  credentials_title: "OAuth Credentials"
  client_id: string        # HubSpot application client ID
  client_secret: string    # HubSpot application client secret  
  refresh_token: string    # OAuth refresh token for automatic renewal

Usage Example:

source:
  type: airbyte/source-hubspot
  config:
    credentials:
      credentials_title: "OAuth Credentials"
      client_id: "${HUBSPOT_CLIENT_ID}"
      client_secret: "${HUBSPOT_CLIENT_SECRET}"
      refresh_token: "${HUBSPOT_REFRESH_TOKEN}"
    start_date: "2023-01-01T00:00:00Z"

Private App Authentication

Private App token authentication for server-to-server access with scoped permissions.

credentials:
  credentials_title: "Private App Credentials"
  access_token: string     # HubSpot Private App access token

Usage Example:

source:
  type: airbyte/source-hubspot
  config:
    credentials:
      credentials_title: "Private App Credentials"
      access_token: "${HUBSPOT_ACCESS_TOKEN}"
    start_date: "2023-01-01T00:00:00Z"

Start Date Configuration

Configures the starting point for incremental data synchronization.

start_date:
  type: string
  format: date-time
  pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
  default: "2006-06-01T00:00:00Z"
  description: "UTC datetime for incremental sync starting point"

Usage Examples:

# Start from specific date
start_date: "2023-01-01T00:00:00Z"

# Start from beginning of current year
start_date: "2024-01-01T00:00:00Z"

# Default behavior (omit for default)
# start_date defaults to "2006-06-01T00:00:00Z"

Experimental Streams

Controls access to experimental or beta data streams that may have unstable schemas.

enable_experimental_streams:
  type: boolean
  default: false
  description: "Enable access to experimental data streams"

Usage Example:

source:
  type: airbyte/source-hubspot
  config:
    credentials:
      credentials_title: "Private App Credentials"
      access_token: "${HUBSPOT_ACCESS_TOKEN}"
    enable_experimental_streams: true

Concurrency Configuration

Controls the number of concurrent workers for parallel data processing.

num_worker:
  type: integer
  minimum: 1
  maximum: 40
  default: 3
  description: "Number of concurrent workers for data extraction"

Usage Examples:

# High throughput configuration
num_worker: 10

# Conservative configuration for rate limit compliance
num_worker: 1

# Default behavior (omit for default)
# num_worker defaults to 3

Incremental Sync Configuration

Controls the lookback window for incremental synchronization to handle late-arriving data.

lookback_window:
  type: integer
  minimum: 0
  default: 0
  description: "Number of days to look back from cursor position for incremental sync"

Usage Examples:

# Handle late-arriving data with 1-day lookback
lookback_window: 1

# Handle significant delays with 7-day lookback
lookback_window: 7

# Default behavior (no lookback)
# lookback_window defaults to 0

Complete Configuration Schema

SourceHubSpotConfig:
  type: object
  required:
    - credentials
  properties:
    credentials:
      oneOf:
        - $ref: "#/definitions/OAuthCredentials"
        - $ref: "#/definitions/PrivateAppCredentials"
    start_date:
      type: string
      format: date-time
      default: "2006-06-01T00:00:00Z"
    enable_experimental_streams:
      type: boolean
      default: false
    num_worker:
      type: integer
      minimum: 1
      maximum: 40
      default: 3
    lookback_window:
      type: integer
      minimum: 0
      default: 0

OAuthCredentials:
  type: object
  required:
    - credentials_title
    - client_id
    - client_secret
    - refresh_token
  properties:
    credentials_title:
      type: string
      const: "OAuth Credentials"
    client_id:
      type: string
      description: "HubSpot application client ID"
    client_secret:
      type: string
      description: "HubSpot application client secret"
    refresh_token:
      type: string
      description: "OAuth refresh token for automatic renewal"

PrivateAppCredentials:
  type: object
  required:
    - credentials_title
    - access_token
  properties:
    credentials_title:
      type: string
      const: "Private App Credentials"
    access_token:
      type: string
      description: "HubSpot Private App access token"

Authentication Flow Details

OAuth Flow:

  1. Application redirects user to HubSpot OAuth authorization URL
  2. User grants permissions and is redirected back with authorization code
  3. Application exchanges code for access and refresh tokens
  4. Connector uses refresh token to obtain fresh access tokens automatically

Private App Flow:

  1. Create Private App in HubSpot developer account
  2. Configure required scopes for data access
  3. Generate access token from Private App settings
  4. Use access token directly in connector configuration

Required Scopes

The connector requires the following HubSpot scopes depending on enabled streams:

Core CRM Scopes:

  • crm.objects.contacts.read
  • crm.objects.companies.read
  • crm.objects.deals.read
  • tickets

Marketing Scopes:

  • content
  • forms
  • email

Engagement Scopes:

  • engagements

Additional Scopes:

  • settings.users.read (for owners)
  • crm.schemas.custom.read (for custom objects)

Install with Tessl CLI

npx tessl i tessl/airbyte-airbyte-source-hubspot

docs

additional-streams.md

authentication.md

crm-streams.md

custom-objects.md

engagements.md

index.md

marketing.md

property-history.md

tile.json