Skip to main content

HubSpot

kHubSpot Integration Guide

Overview

This guide explains how to connect Bridged with HubSpot to sync contacts, deals, and conversation data. The integration supports reading profiles from HubSpot for activation and broadcasting, as well as writing qualified leads and conversation outcomes back to HubSpot.

HubSpot provides multiple API options including REST APIs for real-time operations and SDKs for client-side chat integration . The platform uses date-based API versioning (e.g., 2026-03), and new integrations should always use the latest dated version .

Prerequisites

Before starting, ensure you have:

  • A HubSpot account with API access enabled (available on free and paid tiers)

  • A HubSpot user with Super Admin or App Marketplace Access permissions

  • The HubSpot objects and properties you wish to read from or write to (e.g., contacts, companies, deals)

Connection Methods

Bridged supports two connection methods for HubSpot:

Method

Best for

Setup complexity

API Key (Service Key - Preferred)

Server-to-server, internal integrations, automation

Low

OAuth 2.0

Multi-tenant apps, Marketplace listings, user-specific access

Medium

Recommendation: API Key (Service Key) is the preferred method for production integrations with your own HubSpot account. OAuth 2.0 is supported for multi-tenant scenarios where customers install the integration in their own accounts .

Step 1: Choose Your Authentication Method

Option A: API Key (Service Key) - Preferred

Service keys are in public beta and allow you to query HubSpot's REST APIs directly without OAuth setup .

Limits: Service keys are subject to the same limits as privately distributed apps built on version 2025.2 of the developer platform .

To create a service key:

  1. Log in to your HubSpot account as a Super Admin or user with Developer tools access permission.

  2. Navigate to Development (gear icon → Development).

  3. In the left sidebar menu, go to Keys → Service keys.

  4. Click Create service key in the top right.

  5. Enter a name for the service key (e.g., Bridged Integration).

  6. Click Add new scope and select the required scopes:

    • crm.objects.contacts.read - Read contact data

    • crm.objects.contacts.write - Write contact updates

    • crm.objects.companies.read - Read company data (if needed)

    • conversations.read - Read conversation threads (if using chat)

    • conversations.write - Write messages (if using chat)

  7. Click Update when done, then click Create.

  8. On the service key details page, click Show to reveal the key, then Copy to save it.

Important: Store the service key securely. You cannot retrieve it again after leaving the page .

Option B: OAuth 2.0

Use OAuth if your integration will be installed by multiple HubSpot accounts or listed on the HubSpot Marketplace .

Step 1: Create an App in HubSpot

  1. Navigate to Development → Apps.

  2. Click Create app.

  3. Fill in the app information:

    • App name: Bridged Integration

  4. Go to the Auth tab.

  5. Under OAuth Settings:

    • Redirect URLs: https://gateway.bridged.media/auth/hubspot/callback

    • Required scopes: Select the scopes your integration needs (see Option A for common scopes)

  6. Click Save.

  7. Note your Client ID and Client Secret.

Step 2: Understand the OAuth Flow

HubSpot supports the OAuth 2.0 authorization code grant type, which involves four steps :

  1. Your app redirects the user to HubSpot's authorization URL

  2. User grants access to the requested scopes

  3. HubSpot redirects back with an authorization code

  4. Your app exchanges the code for access and refresh tokens

Authorization URL example :

text

https://app.hubspot.com/oauth/authorize?client_id=YOUR_CLIENT_ID&scope=crm.objects.contacts.read%20crm.objects.contacts.write&redirect_uri=https://gateway.bridged.media/auth/hubspot/callback

Token exchange (handled automatically by Bridged) :

bash

curl --request POST \
  --url https://api.hubapi.com/oauth/2026-03/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data client_id=YOUR_CLIENT_ID \
  --data client_secret=YOUR_CLIENT_SECRET \
  --data code=AUTHORIZATION_CODE \
  --data grant_type=authorization_code \
  --data redirect_uri=https://gateway.bridged.media/auth/hubspot/callback

Token response includes:

  • access_token: Valid for 30 minutes

  • refresh_token: Long-lived, used to generate new access tokens

  • expires_in: Token lifetime in seconds (1800 seconds = 30 minutes)

Step 2: Configure Bridged to Connect to HubSpot

  1. Log in to your Bridged dashboard.

  2. Navigate to the Integrations section in your Bridged dashboard. If you do not see this section, contact support@bridged.media.

  3. Click HubSpot → Connect Account.

  4. Choose your authentication method:

    Option A: API Key (Service Key)

    • Enter your HubSpot Service Key (starts with pat-)

    • Enter your HubSpot Account ID (found in your HubSpot URL after login)

    Option B: OAuth 2.0

    • Enter your Client ID and Client Secret

    • Click Connect with HubSpot

    • You will be redirected to HubSpot to log in and authorize the Bridged app

    • After authorization, you will be redirected back to Bridged

Step 3: Configure Sync Settings

Once connected, configure the following:

Setting

Options

Description

Objects to sync

Contacts, Companies, Deals, Conversations

Choose which HubSpot objects Bridged can access

Sync direction

Read only, Write only, Read + Write

Define data flow

Field mapping

Custom

Map HubSpot properties to Bridged profile attributes

Sync frequency

Real-time (webhooks), Hourly, Daily

Determines how often data is pulled

Bulk sync limit: Each bulk operation is limited to 50 records per request . For larger datasets, Bridged automatically paginates through multiple requests.

Step 4: Configure Webhooks for Real-time Sync (Optional)

For real-time updates, configure HubSpot webhooks:

  1. In your HubSpot account, navigate to Development → Webhooks.

  2. Click Create webhook.

  3. Set the target URL: https://gateway.bridged.media/webhooks/hubspot

  4. Subscribe to events:

    • contact.creation

    • contact.propertyChange

    • conversation.newMessage (if using chat)

  5. Save the webhook configuration.

Note: Webhooks require OAuth authentication. Service keys cannot authenticate webhooks .

Step 5: Test the Integration

  1. In Bridged, go to Integrations → HubSpot → Test Connection.

  2. Confirm that a test contact can be read from HubSpot.

  3. Create a test contact in HubSpot and verify it appears in Bridged (if reading is enabled).

  4. In Bridged, mark a test contact as "qualified" and verify it writes back to HubSpot.

Using the HubSpot API for Testing

You can verify your integration by making a test API call with your service key :

bash

curl --request GET \
  --header "Authorization: Bearer YOUR_SERVICE_KEY" \
  --url "https://api.hubapi.com/crm/v3/objects/contacts?limit=10&archived=false"

Common Use Cases

Playbook

Direction

Description

Activation

Read

Pull contact list from HubSpot to broadcast WhatsApp messages

Qualification Agent

Read + Write

Read historical engagement, score contact, write score back to HubSpot

Nurture & Conversion

Write

Log conversation outcomes and qualified contacts to HubSpot

Conversations

Read + Write

Sync chat conversations and messages with HubSpot inbox

Rate Limiting & Performance

  • Rate limits: HubSpot enforces 100 requests per 10 seconds for most endpoints on the free tier. Higher limits are available on paid plans .

  • Bulk operations: Maximum 50 records per request.

  • For large data volumes, use incremental sync to minimize API usage .

Security & Permissions

  • Bridged supports both Service Keys (preferred) and OAuth 2.0 authentication.

  • Service keys can be rotated every six months for security. If compromised, you can rotate and expire immediately .

  • Credentials are encrypted and never stored in plain text.

  • All API calls are made over TLS 1.2+.

  • Access tokens expire after 30 minutes; refresh tokens are long-lived .

Service Key Management

Action

How to perform

Rotate key

Development → Keys → Service keys → Click key → Rotate

Expire immediately

Rotate and expire now (if compromised)

Expire in 7 days

Rotate and expire later (regular rotation)

Cancel rotation

Click Cancel rotation to keep original key

Delete key

Click Delete and confirm by typing key name

Troubleshooting

Issue

Likely cause

Solution

Connection fails

Invalid service key or scopes

Verify service key and ensure required scopes are selected

No data appears

Field mapping incorrect

Check that HubSpot property names match Bridged profile attributes

Write fails

Missing write scopes

Ensure crm.objects.contacts.write scope is added to service key

Bulk operation fails

Exceeds 50 record limit

Split your data into batches of 50 records or fewer

Rate limiting (429)

Too many API calls

Reduce sync frequency; paid plans have higher limits

Authentication errors

Expired OAuth token

Use refresh token to generate new access token

Webhooks not working

Service key limitation

Webhooks require OAuth authentication, not service keys

OAuth installation fails

User lacks permissions

User must be Super Admin or have App Marketplace Access

Support

For integration support, contact your Bridged account manager or email support@bridged.media.