HubSpot Integration Guide
Marketing and CRM - HubSpot
Overview
This guide explains how to connect Bridged with HubSpot to sync contact data. The integration supports reading contact profiles from HubSpot for activation and broadcasting, as well as writing qualified lead data back to HubSpot.
HubSpot provides REST APIs for real-time operations. The platform uses date-based API versioning (e.g., 2026-03), and new integrations should always use the latest dated version.
Common Use Cases
Workflow | Direction | Description |
|---|---|---|
Activation | Read + Write | Pull contact list from HubSpot to broadcast activation templates through all channels and write back on CRM for different campaigns |
Connection | Read + Write | Read historical engagement, contact intent and declared data, and write back connection matches |
Acquisition | Write | Log qualified contacts and outcomes to HubSpot |
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 Developer tools access permissions
The HubSpot objects and properties you wish to read from or write to (e.g., contacts)
Connection Method
Bridged connects to HubSpot using an API Key (Service Key). This is currently the only supported authentication method and is sufficient for all Bridged HubSpot use cases, including server-to-server sync of contact data.
Step 1: Create a Service Key
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:
Log in to your HubSpot account as a Super Admin or user with Developer tools access permission.
Navigate to Development (gear icon → Development).
In the left sidebar menu, go to Keys → Service keys.
Click Create service key in the top right.
Enter a name for the service key (e.g., Bridged Integration).
Click Add new scope and select the required scopes:
crm.objects.contacts.read - Read contact data
crm.objects.contacts.write - Write contact updates
crm.schemas.contacts.read - read property definitions
crm.schemas.contacts.write - create/edit property definitions
Click Update when done, then click Create.
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.
Step 2: Configure Bridged to Connect to HubSpot
Log in to your Bridged dashboard.
Navigate to the Integrations section in your Bridged dashboard. If you do not see this section, contact support@bridged.media.
Click HubSpot → Connect Account.
Enter your HubSpot Service Key (starts with pat-).
Enter your HubSpot Account ID (found in your HubSpot URL after login).
Click Connect with HubSpot.
Using the HubSpot API for Testing
You can verify your integration by making a test API call with your service key:
curl --request GET \
--header "Authorization: Bearer YOUR_SERVICE_KEY" \
--url "https://api.hubapi.com/crm/v3/objects/contacts?limit=10&archived=false"
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 Service Key authentication only.
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+.
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 |
Note: Key rotation is customer-initiated. Bridged does not automatically rotate service keys - if you generate a new key in HubSpot, you must update it in the Bridged dashboard.
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 |
Rate limiting (429) | Too many API calls | Reduce sync frequency; paid plans have higher limits |
Authentication errors | Invalid or expired service key | Verify the service key is correct and active; rotate the key if needed |
Support
For integration support, contact your Bridged account manager or email support@bridged.media.