You cannot make any changes to External Platform Integrations without having either an Administrator or an Editor with PII access in InOne. Refer to User Roles for further information.
This guide explains how to set up the HubSpot integration in InOne. Once configured, InOne pulls contact records from your HubSpot account on a schedule and syncs them as user profiles and behavioral events in Insider One.
The table below summarizes the key capabilities and behavior of the integration.
Capability | Details |
|---|---|
Auth method | OAuth 2.0 (HubSpot) |
Data flow | One-way: HubSpot to Insider One |
Object types | Contact (default). Custom HubSpot events are surfaced as event-parameter sources. |
Sync modes | List Contacts (sync all contacts on a schedule) or Get Contact (sync a specific contact on a schedule) |
Sync behavior | Incremental in List Contacts mode (only contacts updated since the last successful run). Per-run fetch in Get Contact mode. |
Supported data | User identifiers, profile attributes, events, and event parameters |
Scheduling | Configurable cron schedule (UTC) |
Requirements
Before the integration, ensure you have the following information.
Information | Details |
|---|---|
HubSpot OAuth Client ID | From your HubSpot developer account under Apps > your app > Auth tab. |
HubSpot OAuth Client Secret | From the same Auth tab. |
HubSpot scopes |
|
HubSpot user permission | The authorizing HubSpot user must have access to the contacts and custom events you intend to sync. |
The integration connects through the HubSpot CRM v3 REST API at
api.hubapi.com. The OAuth access token is refreshed automatically.
Step 1: Create a new integration
Navigate to InOne > Components > Integrations > External Integrations.
Search for "HubSpot" and select it.
Give the integration a unique name and click Save.
Step 2: Connect your HubSpot account
Before connecting your HubSpot account, make sure you have the following information in place.
Field | Description |
|---|---|
Authorize URL | OAuth 2.0 Authorization URL for HubSpot. Defaults to |
Token URL | OAuth 2.0 Token URL for HubSpot. Defaults to |
Scopes | Defaults to |
Client ID | The Client ID of your HubSpot OAuth app. |
Client Secret | The Client Secret of your HubSpot OAuth app. |
Create a Custom OAuth App in HubSpot
This step is performed in your HubSpot developer account, not in InOne.
Log in to your HubSpot developer account at
app.hubspot.com/developers.From the Apps dashboard, click Create app.
On the App info tab, fill in:
Public app name: e.g.
Insider One IntegrationDescription: optional internal description
Logo: optional
Switch to the Auth tab.
Under Redirect URLs, add:
https://oauth2.connect.insiderone.com/callbackUnder Scopes, click Add new scope and select:
crm.objects.contacts.read(Optional) Any additional read scopes required for your custom events
Click Save. HubSpot generates the Client ID and Client Secret.
From the same Auth tab, copy:
Client ID
Client Secret
Paste both values into the integration's Step 2 form in InOne.
Click Connect. A browser pop-up opens for HubSpot OAuth authorization. Select the HubSpot account to connect, approve the requested scopes, and close the pop-up. The status indicator turns green to confirm the connection.
Click Next to proceed.
Step 3: Sync Target
Choose what to sync from HubSpot.
Option | Description |
|---|---|
List Contacts (default) | Syncs all HubSpot contacts on the configured schedule. Incremental: only contacts updated since the last successful run are fetched. |
Get Contact | Syncs a single HubSpot contact on the configured schedule. Use this for testing or targeted use cases. The contact picker is loaded live from your HubSpot account. |
The contact field list shown on the next pages is fetched live from HubSpot. It includes:
All contact properties on the connected account (system properties starting with
hs_are filtered out except for a useful subset, such ashs_object_id,hs_email_domain,hs_language,hs_analytics_source).Custom event property fields, prefixed with the event label (e.g.
[Newsletter Signup] source_page).
Click Next when done.
Step 4: Identifier Mapping
Map HubSpot contact fields to Insider One identifier types. At least one mapping is required. Records with no valid identifier value are skipped.
Field | Description |
|---|---|
Identifier Type | The Insider One identifier type: Email Address, Phone Number, UUID, or any custom identifier. |
Source Field | The HubSpot contact field providing the identifier value. |
Common mappings: Email Address to email, Phone Number to phone, UUID to hs_object_id.
Click + Add to Identifier Mappings to add rows. Click Next when done.
Step 5: Attribute Mapping
Map HubSpot contact fields or static values to Insider One user profile attributes.
Column Mappings: Each row maps a HubSpot contact property to an Insider One attribute. The field value is written to the matched user profile on each sync run.
Fixed Value Mappings: Sets a static value on every synced profile, regardless of what HubSpot contains. Common use: set crm_source to hubspot to tag all synced records by origin.
Click Next when done.
Step 6: Event Mapping (Optional)
Map HubSpot custom event definitions to Insider One event types. One event is sent per HubSpot custom event record.
Field | Description |
|---|---|
HubSpot Event | The custom event definition from your HubSpot account (loaded live from the connection). |
Insider Event Type | The Insider One event type fired when this HubSpot event is received. |
Custom events not listed here are ignored. Standard contact-level activities (form submissions, page views) are surfaced as part of contact properties; use Attribute Mapping or Event Parameter Mapping to reference them.
Click Next when done.
Step 7: Event Parameter Mapping (Optional)
Active only when event mapping is enabled. Maps HubSpot fields or fixed values to Insider One event parameters (e.g. order_value, product_name).
Column Mappings: Each row maps a HubSpot event property or contact property to an Insider One event parameter.
Fixed Value Mappings: Sets a static parameter value on every event sent in this run.
Changing the event mappings on the previous page resets the parameter mappings on this page (you will be prompted before this happens).
Click Next when done.
Step 8: Sync Options
Field | Description |
|---|---|
Schedule | Cron expression (UTC) for how often the integration runs. Example: |
Skip Hook | Suppresses Architect journey triggers for all users upserted in this run. Enable for large historical imports to avoid mass journey activation. |
Identifier Settings | Controls behavior when an identifier value fails validation (skip the identifier, skip the entire record, or fail the run). |
Phone Number Settings | Normalizes phone values to E.164 format and optionally adds a country code. |
Boolean Settings | Controls how HubSpot boolean values are converted before upsert (HubSpot returns booleans as the strings |
Click Finish to save and activate the integration.
How does the Sync Flow work?
Step | What happens |
|---|---|
Watermark | Each successful run records the start timestamp. The next run filters HubSpot contacts where |
Pagination | Contacts are fetched in pages of 100 using HubSpot's Search API cursor ( |
Batching | Contacts are upserted to Insider One in batches of 1,000 per request. Remaining records are flushed at the end of the run. |
Failure handling | If a run fails, the watermark is not advanced, so the same window is retried on the next run. If individual upsert batches fail, the run completes, but the watermark is held back so failed records are retried. |
HubSpot 10,000-result search cap: The HubSpot Search API caps any single query at 10,000 matching contacts. If a sync run hits this cap, the integration logs a warning. Schedule the integration frequently enough that no single incremental window exceeds 10,000 updated contacts.
For an initial backfill of accounts larger than this, run the integration on a tight schedule until the watermark catches up.
Troubleshooting
Symptom | What to check |
|---|---|
OAuth connection fails | Verify Client ID and Client Secret. Confirm the HubSpot app is installed on the target HubSpot account and that the redirect URL is |
"HubSpot connection is missing an access token" error | Re-authorize the HubSpot OAuth connection from Step 2. The OAuth flow may not have completed successfully. |
No fields available in mapping steps | The field list is fetched live via the HubSpot Properties API. Confirm the connected user has “Read access” to contacts on the HubSpot account. |
Contacts not syncing | Confirm Sync Target is set to List Contacts and the schedule is active. On incremental runs, only contacts updated in HubSpot since the last successful run are returned, so a run with zero records is correct when nothing has changed. |
Search cap warning in Slack | A single incremental window matched more than 10,000 HubSpot contacts. Run the schedule more frequently so each window stays under the cap, or perform a one-time backfill on a tight schedule. |
Records are missing in Insider One | Confirm that at least one Identifier Mapping is set and the mapped HubSpot field contains valid, non-null values. Check the Executions tab for upsert error details. |
Sync triggering unintended journeys | Enable Skip Hook in Sync Options. This is especially important for large historical backfills. |
Custom events not firing | Confirm the HubSpot event definition is selected in Event Mapping and that records of that event exist in the sync window. Map at least one Event Parameter if you need additional context on the Insider event. |
Frequently Asked Questions
Q: Does the integration fetch all HubSpot contacts on each run or only changes?
A: In List Contacts mode, only contacts updated since the last successful run are fetched, using HubSpot's lastmodifieddate filter. The first run pulls all contacts. In Get Contact mode, the configured contact is re-fetched on every run.
Q: How does the integration handle the HubSpot 10,000-result search cap?
A: The HubSpot Search API truncates any query at 10,000 results. The integration detects when HubSpot's reported total exceeds the actual fetched count and posts a Slack alert. To stay under the cap, run the integration on a frequent enough schedule that each incremental window contains fewer than 10,000 updated contacts.
Q: Will syncing contacts trigger Architect journeys?
A: By default, yes. Enable Skip Hook in Sync Options to suppress journey triggers for all records in a run. Enable this for any historical backfill.
Q: Can I sync custom HubSpot objects (Companies, Deals, Tickets)?
A: Not in this version. The current integration syncs the Contact object only. Custom HubSpot event records are supported through Event Mapping.
Q: Can I sync the same HubSpot contact with both attribute and event mappings?
A: Yes. Configure both Attribute Mapping and Event Mapping. Each contact updates the user profile, and one event is sent per matched HubSpot custom event record.
Q: What happens if a sync run fails?
A: The integration posts a Slack alert and preserves the previous watermark, so the next run retries the same window. If only some upsert batches fail, the watermark is also held back, ensuring failed records are retried on the next run.
Q: Do I need a separate HubSpot OAuth app per InOne integration instance?
A: No. A single HubSpot OAuth app can authorize integrations across multiple HubSpot accounts. You authorize the same app against your own HubSpot account when you connect.