Skip to main content

​
Overview

The HubSpot integration connects Alysio to HubSpot CRM through OAuth 2.0 using Paragon Connect. This integration supports secure, scoped read and write access to CRM data so revenue teams can query, analyze, and update HubSpot from within Alysio. Alysio can read and write CRM records such as contacts, companies, deals, tasks, notes, emails, meetings, and calls. Write access enables fast workflows like updating fields, logging activity, creating records, and keeping pipeline data current from conversational prompts. Alysio respects user-granted scopes at all times. Users can only perform the operations their HubSpot authorization permits.

​
Primary Use Cases

Use the HubSpot integration to: Query and analyze HubSpot CRM data through Alysio’s conversational interface
Create and update HubSpot CRM records from natural language prompts
Log activity such as notes, calls, meetings, and emails
Sync HubSpot users and owners for provisioning and mapping
Support cross-tool visibility by combining HubSpot with other connected systems
Keep pipeline operations moving without switching tools

​
Supported HubSpot Objects

Alysio can work with the following HubSpot CRM objects through this integration: Contacts
Companies
Deals
Tasks
Notes
Emails
Meetings
Calls Depending on scopes granted, Alysio may also access supporting metadata such as users, owners, pipelines, stages, and object properties.

​
Authentication

​
Method

OAuth 2.0 via Paragon Connect

​
Redirect URI

https://passport.useparagon.com/oauth

​
Token Handling and Security Model

OAuth tokens are issued by HubSpot and managed by Paragon. Alysio does not store HubSpot OAuth tokens.
Paragon stores and refreshes tokens securely.
Each tenant connection is isolated using a signed X Paragon Credential header.
Tokens are automatically refreshed through Paragon.
When the integration is uninstalled, Paragon removes credentials and HubSpot access stops immediately.
Alysio enforces only the scopes granted during authorization.

​
Required Scopes

The HubSpot integration uses the following scopes.

​
Required scopes

crm.objects.companies.read
crm.objects.companies.write
crm.objects.contacts.read
crm.objects.contacts.write
crm.objects.deals.read
crm.objects.deals.write
crm.objects.owners.read
crm.objects.users.read
crm.schemas.custom.read
oauth
sales-email-read
settings.users.read
settings.users.teams.read

​
Optional scope

timeline

​
Scope Justification

crm objects contacts read write
Read, create, and update contact records crm objects companies read write
Read, create, and update company records for account based workflows crm objects deals read write
Retrieve, create, and update deal data for pipeline execution timeline
Read HubSpot engagement timeline for activity visibility and analysis sales email read
Read sales email engagement data when enabled oauth
Required for OAuth authorization crm objects owners read and crm objects users read
Map HubSpot owners and users to Alysio workspace identities schemas custom read
Detect and interpret custom properties and CRM schema dynamically settings users read and settings users teams read
Sync user and team hierarchy for provisioning and permission mapping

​
API Usage

All HubSpot API requests route through Paragon’s secure proxy: /sdk/proxy/hubspot/https://api.hubapi.com Alysio performs read and write operations but does not delete CRM data through this integration.

​
Read Endpoints Used

Account info
GET /account-info/v3/details
Retrieve connected HubSpot account details Owners
GET /crm/v3/owners
List CRM owners for mapping and assignment Users and roles
GET /settings/v3/users
GET /settings/v3/users/roles
Retrieve users, roles, and access structure CRM object search
POST /crm/v3/objects//search
Search records across supported object types Associations
GET /crm/v4/objects///associations/
Retrieve relationships between CRM objects Pipelines and stages
GET /crm/v3/pipelines///stages
Retrieve pipeline stage definitions Object properties
GET /crm/v3/properties/
Retrieve object metadata and property definitions

​
Write Endpoints Used

Create
POST /crm/v3/objects/
Create CRM records across supported object types Update
PATCH /crm/v3/objects//
Update CRM records by ID Merge companies
POST /crm/v3/objects/companies/merge
Merge duplicate company records Default associations
PUT /crm/v4/objects///associations/default//
Create default associations between objects

​
Rate Limiting and Error Handling

Errors are handled through a structured client error layer. HTTP status errors are surfaced as actionable errors
Transient 5xx responses are retried when appropriate
204 No Content responses are treated as successful updates

​
MCP Tools

The HubSpot MCP tools list should be populated from your HubSpot MCP server implementation so this page mirrors actual tool availability inside Alysio. Recommended structure for the tools section: Tool name
What it does in plain language
What it reads or writes
Example user prompts If you paste your HubSpot MCP tool list, I’ll convert it into the same tool table format used across the rest of your docs.

​
App Behavior

HubSpot API calls are triggered when users ask questions or request actions in Alysio. Requests are proxied through Paragon and executed only within granted scopes
Updates are performed per user action and are not batch written by default
Cached identifiers such as user_id and owner_id prevent duplicate mapping and preserve identity consistency
If HubSpot marks users as archived, Alysio soft deletes corresponding local mappings
All operations remain scoped and auditable

​
Example Workflow

User asks Create a new deal for Acme Corp Alysio validates that crm objects deals write is granted
Alysio sends a proxied request through Paragon
HubSpot creates the deal and returns the deal ID
Alysio stores only the returned record identifier needed for mapping and referencing

​
Troubleshooting

​
Missing Admin Permissions

If you see an error such as App Marketplace access permission set required, the connecting HubSpot user likely does not have permission to install or connect apps. Solution
A HubSpot Super Admin can enable App Marketplace access in: Settings → Users and Teams → Permission Sets → Account → Settings Access → App Marketplace Access

​
401 Unauthorized

The connection is missing, expired, or revoked. Solution
Reconnect HubSpot in Alysio under Settings → Integrations

​
403 Forbidden

The requested operation exceeds granted OAuth scopes. Solution
Reauthorize HubSpot and ensure the required scopes were approved

​
Legacy App Installation Conflicts

If your workspace is mixing legacy installations with newer framework installs, authentication or scopes may fail unexpectedly. Solution
Confirm the installation uses HubSpot Projects Framework 2025.2 or later and reinstall if needed

​
Support

support@alysio.ai

​
Version History

June 2025
Legacy HubSpot app created November 2025
Migrated to HubSpot Projects Framework 2025.2 Ongoing
Security and compliance enhancements including improved token isolation and dynamic scope validation

​
Data Flow Summary

A HubSpot user initiates OAuth authorization
Authorization redirects through Paragon
Paragon manages tokens and refresh and isolates credentials per tenant
Alysio validates granted scopes before every request
HubSpot API enforces permissions and returns data and responses Alysio cannot exceed granted scopes
All data travels over HTTPS
Tokens are not exposed or stored by Alysio
On uninstall, the integration is deauthorized and sync stops immediately.