HubSpot Service Account Requirements

📘
Recommended: Upside recommends connecting HubSpot using a Super Admin account. This is the simplest path and avoids permissions issues entirely. The granular permissions approach described below should only be used if your organization's security policy requires minimum-necessary access.

HubSpot Permissions

HubSpot has two distinct permission systems that interact with each other:

User-level permissions — These control what a user can see and do inside the HubSpot application UI. They are configured in Settings → Users & Teams by editing a user's permissions.
API permissions (scopes) — These control what a user is allowed to do via the HubSpot API, or what an application the user installs and authorizes can do via the API. Scopes are granted when a user authorizes an OAuth connection.

HubSpot internally maintains a mapping between these two permission systems, but the mapping is not one-to-one and HubSpot does not publish what that mapping is.

This has an important practical consequence: certain API endpoints that retrieve data require a specific OAuth scope. In order for a user to satisfy that scope, they may need a combination of multiple different UI permissions granted to their account. If the user's UI permissions do not satisfy all of the scope's internal requirements, the API call will fail — even if the scope itself was requested during the OAuth flow.

Why These Permissions May Appear Broader Than Expected

Upside uses Fivetran for read-only data syncs and does not make API calls that modify or create data in your HubSpot instance.

However, in order to satisfy HubSpot's internal permission-to-scope mapping for reading certain types of data, such as email engagement events and web page visit activity, HubSpot requires granting the service account user elevated UI permissions that may appear broader than what a read-only integration would need.

⚠️
Important: The set of permissions outlined below is the absolute minimal set of HubSpot UI permissions that can be granted to a service account user and still satisfy the requirements for Upside to sync all required data types. Attempting to grant any lesser set of permissions will result in the sync not working. This is a limitation of HubSpot's permissions system, not a choice by Upside.

Service Account Setup

1. Create the Service Account User

Create a dedicated user in HubSpot for the Upside integration (or use an existing service account).

When setting up the user, you must choose the option to assign permissions from scratch rather than copying from an existing user or using a preset. Then proceed to assign the exact set of permissions detailed below.

2. Assign Permissions

Configure the following permissions on the service account user. These are organized by the permission categories shown in the HubSpot UI.

📘
Note on View permissions: Where a permission offers a scope selector (e.g., "Theirs" vs. "All"), you must set it to All (e.g., "View (All contacts)"). Upside needs to read all records regardless of ownership.

CRM Objects

Permission	Access Level
Contacts	View (All contacts)
Companies	View (All companies)
Deals	View (All deals)
Tickets	View (All tickets) and Edit (All tickets)
Tasks	View (All tasks)
CRM emails	View (All CRM emails)
Meetings	View (All meetings)
Calls	View (All calls)
Notes	View (All notes)

CRM Tools

Permission	Access Level
Export	On

Marketing

Permission	Access Level
Forms	On
Files	View
Marketing Access	On
Ads	View and Publish
Campaigns	View and Publish
Marketing email	View, Edit, and Publish
CTA	View
SMS	View
Lead Scoring	View
Deal Scoring	View
Social	All accessible accounts
Marketing Events	On
Blog	View, Edit, and Publish
Landing pages	View, Edit, and Publish
Website pages	View, Edit, and Publish
HubDB	View, Edit, and Publish
URL Redirects	View and Publish
Design tools	On
Content staging	On

Commerce

Permission	Access Level
Invoices	View (Their invoices) — this is the default and can’t be changed

Reporting

Permission	Access Level
Goals	View (All goals)
Reports Access	On
Dashboard, reports, and analytics	View
Marketing reports	On
Custom Events	View

Settings Access

Permission	Access Level	Note
App Marketplace access	On	This is the permission that allows the user to actually install the Fivetran HubSpot app.
Edit property settings	On
Website settings	On
User table access	On	This allows Upside to see the HubSpot users to identify and categorize your team members.

What This Enables Upside to Sync

With the permissions above, Upside syncs the following data from your HubSpot instance:

CRM data:

Contacts
Companies*
Deals*
Email records
Meeting records
Call records

Marketing automation data:

Marketing email events (opens, clicks, bounces, etc.)*
Contact-level website page view activity*
Form fill activity*

📘
Deals and Companies are relevant for organizations using HubSpot as a CRM. Marketing email events, website page view activity, and form fill activity are relevant for organizations using HubSpot to track these activity types.

Does Upside Write Data to HubSpot?

No. Upside only reads data from HubSpot. The Fivetran connector performs read-only syncs and does not create, modify, or delete any records in your HubSpot instance.

Troubleshooting

Sync Failures Due to Insufficient Permissions

If a sync fails with a permissions error, the most likely cause is that the service account user is missing one or more of the UI permissions listed above.

Resolution options:

Use a Super Admin account (recommended) — This eliminates all permissions issues
Verify all permissions match the tables above exactly — Even a single missing permission can cause a scope to not be satisfied
Contact Upside Support — We can help identify which specific permission is missing based on the error details