Connecting HubSpot

Open Integrations and click Connect HubSpot. You are sent to HubSpot to choose the portal and approve the access Alignify asks for, then you come back to Alignify. The first schema sync starts automatically so agents know your pipelines, stages and properties. Only an owner or admin of the workspace can connect HubSpot, and your HubSpot user needs permission to install apps in that portal (usually a HubSpot super admin). If HubSpot shows an error or you cancelled, click Connect HubSpot again.

On the HubSpot access screen Alignify asks to:

• read contacts, companies, deals and tickets, and the sales emails logged on them;
• read your pipelines, stages and property definitions (the schema);
• write contacts, companies, deals and tickets, used only for approved updates: notes, tasks, field changes and record links;
• create the Alignify properties (alignify_…) in your portal.

Calls, meetings, notes and tasks are read through the contact and deal permissions. HubSpot shows these as scopes, for example crm.objects.deals.read or sales-email-read.

Alignify reads records only when an agent runs (or a schedule fires) and only what that agent needs: the record, its related records and recent activity, with email bodies shortened to excerpts. It keeps a copy of your HubSpot structure (pipelines, stages, properties), not of your whole CRM. It writes only the updates listed in WriteBacks: notes, tasks, Alignify fields, approved field changes and record links. It never deletes records and never sends emails from your HubSpot. Dedup & Merge merges two records only after an admin approves that pair.

If Integrations shows "Needs reconnect", a banner asks you to reconnect, or an agent or WriteBack says a permission is missing, an owner or admin opens Integrations and clicks Reconnect HubSpot, then approves the HubSpot access screen again with the same portal. Reconnecting keeps your runs, reports, schedules and settings, and resumes schedules that were paused because HubSpot was disconnected. A reconnect is needed after Alignify starts asking for a new permission, after someone uninstalled the app in HubSpot, or after the HubSpot user who connected it lost access. Members cannot reconnect; they see "Only workspace admins can connect HubSpot. Ask a workspace admin."

The email "Reconnect HubSpot to keep your Alignify agents running" goes to workspace owners and admins when HubSpot stops accepting Alignify's access. Agents and schedules are paused until someone reconnects, and nothing is charged while they are paused. It is sent once per problem, not repeatedly, together with an in-app notification. Click Reconnect HubSpot in the email (or open Integrations → Reconnect HubSpot) and approve the HubSpot screen with the same portal; your reports and settings stay. If you removed the Alignify app in HubSpot on purpose, you can ignore it.

Both show "Needs reconnect" on Integrations and the red "HubSpot access was revoked — reconnect to resume agents" banner, and both are fixed with Reconnect HubSpot. Access lost means the Alignify app was uninstalled from HubSpot or HubSpot rejected its access for good: it never fixes itself and schedules are paused until an admin reconnects. "Alignify could not refresh its HubSpot access" means HubSpot refused our sign-in to your portal; Alignify checks again every hour and on the next run, and if HubSpot accepts it again the status returns to Connected and paused work resumes by itself. Reconnecting fixes either case at once.

Short outages, on HubSpot's side (HubSpot is down or busy) or ours, do not mark your connection as broken: there is no banner, no reconnect email and nothing to do. A run hit by such an outage is retried; if it still fails it is marked Failed and its credits are returned. Such a run says "We couldn't reach HubSpot just now. The run wasn't charged — please try again in a few minutes.": run it again a little later. Only "HubSpot token refresh failed. Reconnect HubSpot or verify OAuth credentials." means HubSpot refused Alignify's access and an owner or admin must reconnect.

This red banner means HubSpot stopped accepting Alignify's access. Its first line says why: "The Alignify app was uninstalled from your HubSpot account", "HubSpot stopped accepting Alignify's access" or "Alignify could not refresh its HubSpot access". Until it is fixed, new runs are refused with "Nothing was charged", scheduled work is paused, and owners and admins get one "Reconnect HubSpot to keep your Alignify agents running" email. An owner or admin clicks Reconnect HubSpot; everything resumes. Members see "Ask a workspace owner or admin to reconnect HubSpot."

Uninstalling the app in HubSpot cuts Alignify's access. Alignify notices when HubSpot tells us, at its hourly connection check or the next time it uses the connection (a run, a schedule or a record search), then marks HubSpot as needing a reconnect, pauses schedules, shows the "access was revoked" banner and emails owners and admins once. Your reports and settings stay. To continue, reconnect from Integrations. To stop using Alignify for good, also see deleting the workspace.

This yellow banner means the connection works but was approved before Alignify asked for a permission it now needs (for example ticket access or creating Alignify properties). Only the agents and updates that need that permission are affected: they are refused or wait with "Needs HubSpot permission". An owner or admin clicks Reconnect HubSpot on Integrations and approves the new permission; nothing else changes.

A missing scope means your connection was approved before Alignify needed that permission (for example ticket reading for ticket agents, sales email reading for email analysis, or write permissions for HubSpot updates). Agents that need it say what could not be read, or are refused before they start, with nothing charged. WriteBacks that need it show "Needs HubSpot permission". Reconnect HubSpot to grant it.

Ticket Categorization, QBR Prep and ticket searches need permission to read tickets. Connections approved before Alignify asked for it see this message, and nothing is charged. An owner or admin opens Integrations, clicks Reconnect HubSpot and approves ticket access, then runs the agent again.

Some custom agent data (line items, products, quotes, owner names, custom objects) needs extra HubSpot permissions that a connection may not have. Those items are greyed out with "Reconnect HubSpot to allow …". An owner or admin can reconnect HubSpot and approve the extra permission on the HubSpot screen. If the item stays unavailable after reconnecting, it is not offered for your workspace yet; ask for a person in the support chat.

Alignify keeps a copy of your HubSpot structure (pipelines, stages, properties), not your records. It refreshes automatically. If a new pipeline, stage or property does not show up yet (for example in the Schedules pipeline list), click Sync schema on the Integrations page.

Owners and admins can disconnect HubSpot on the Integrations page. Alignify stops reading your CRM, scheduled agents stop running, and HubSpot is asked to revoke our access. Your past reports stay in Alignify until they expire or you delete the workspace. Reconnect any time from Integrations.

A workspace connects to one HubSpot portal. Reconnecting with a different portal is refused with "This workspace is linked to a different HubSpot portal. Reconnect using the original portal." To work with a second portal you need a separate workspace for it; ask for a person in the support chat to set it up or to move a workspace to another portal.

• "HubSpot authorization was cancelled or denied": you closed or declined the HubSpot screen; click Connect HubSpot again.
• "The OAuth session expired or was invalid": start again from Integrations in the same browser.
• "HubSpot authorized successfully but we could not save the connection": try again; if it repeats, ask for a person.
• "That HubSpot sign-in link has already been used or timed out. Click Connect HubSpot to try again.": you opened an old confirmation link (they work once, for 10 minutes). Click Connect HubSpot (or Reconnect HubSpot) again. If HubSpot is already connected, an old link simply opens Integrations with no error.
• "This HubSpot portal is already connected to another Alignify workspace": disconnect it in the other workspace first, or ask for a person.