Documentation

HubSpot Integration Guide

Connect your HubSpot account to Clareefai to import contacts as promoters and start advocacy workflows the moment a deal is won.

Last updated: October 23, 2026

1. Before you start

You need three things before you connect:

  • A Clareefai vendor account. Sign in to the Clareefai vendor app. If you do not have an account yet, request access from the Clareefai website.
  • Permission to install apps in HubSpot. Your HubSpot user must be allowed to install apps — typically a Super Admin, or any user granted app-installation permission.
  • HubSpot contacts with email addresses. Clareefai identifies promoters by email address, so contacts without one cannot be imported.

2. Connecting HubSpot

Connecting takes about a minute. There is nothing to configure, no API key to paste, and no code to install.

  1. 1

    Open CRM Import

    In the Clareefai vendor app, go to Promoters, then CRM Import.

  2. 2

    Choose HubSpot

    Select the HubSpot card from the available import sources.

  3. 3

    Authorize

    Click Connect to HubSpot. You are redirected to HubSpot, where you pick the account to connect and review the permissions Clareefai is requesting.

  4. 4

    Confirm

    Once you approve, HubSpot sends you back to Clareefai. The page now shows Connected to HubSpot together with your Hub ID.

Clareefai stores an encrypted access token scoped to your account only. Tokens are refreshed automatically in the background and are never exposed to your browser.

Vendor app: vendor.clareefai.com

3. Permissions explained

Clareefai asks for two groups of permissions. Only the required group is needed to connect. The optional group powers deal-based workflow triggers. You can decline it and the connection still works. Clareefai never writes to HubSpot.

Required to connect

  • oauth

    Standard permission HubSpot uses to establish the connection.

  • crm.objects.contacts.read

    Read your contacts so you can browse, search, and select who to import into Clareefai.

  • crm.schemas.contacts.read

    Read your contact property definitions — names and labels only, never record values — to build the field-mapping step of the import wizard.

Optional

  • crm.objects.deals.read

    Read your deals so a workflow can start when one reaches the stage you choose, such as Closed Won. Without it, the HubSpot deal trigger is unavailable.

  • crm.schemas.deals.read

    Read your deal property and pipeline definitions, names and labels only, so you can pick the stage that starts a workflow.

Declining an optional permission never blocks the connection — the matching feature is simply unavailable. To grant one later, disconnect and reconnect, approving it on the HubSpot authorization screen.

4. Importing contacts as promoters

The import wizard walks you through six steps. Nothing is saved into Clareefai until the final one, so you can back out at any point.

  1. 1

    Source

    Choose HubSpot as the import source.

  2. 2

    Connect

    Connect your HubSpot account, or continue straight through if you are already connected.

  3. 3

    Select

    Click Fetch Contacts & Continue to load your contacts into a searchable table. Search or sort by name, email, company, job title, lifecycle stage, or phone, change the page size, and tick exactly the contacts you want.

  4. 4

    Mapping

    Your HubSpot fields are mapped to Clareefai fields automatically. Review the mapping and adjust anything you want to change.

  5. 5

    Review

    Check the valid record count and any validation issues before you commit.

  6. 6

    Complete

    Click Save Contacts. Your selection is imported and appears under Promoters.

Contacts you will not be able to select

  • No email address. Clareefai identifies promoters by email, so these rows cannot be imported.
  • Already imported. The contact is already in Clareefai. This is what stops repeat imports from creating duplicates.

  • Every imported record is tagged with a HubSpot badge in your promoter list, so you always know where it came from.

  • Large selections are imported in batches automatically — you never need to split them up yourself.

  • A single fetch loads up to 5,000 contacts. If your account holds more than that, use search to narrow down to the people you need.

5. Starting workflows when a deal is won

Let your pipeline drive advocacy. When a deal reaches the stage you choose, a Clareefai workflow can automatically start an advocacy action for the associated contact, for example a review request or a satisfaction survey.

  1. 1

    Create a workflow

    Go to Automations in the vendor app and create a new workflow.

  2. 2

    Choose the HubSpot trigger

    Pick the CRM record changes trigger. Set CRM to HubSpot, Record type to Deal, and choose the change that should start the workflow, such as Is won. Stages and pipelines are read live from your HubSpot account.

  3. 3

    Add actions and activate

    Add the actions you want, such as a review request or a survey, then click Activate.

How it works

  • Checks run only while a workflow is active. Clareefai periodically checks your deals for the chosen change and stops as soon as the workflow is paused or deleted.
  • Only what the trigger needs is read. The deal name, stage, amount, pipeline and the associated contact. Nothing is stored beyond what the workflow run needs.
  • Nothing is written to HubSpot. Clareefai never creates, modifies or deletes HubSpot records.

This feature requires the optional deal permissions. If you declined them, the HubSpot option does not appear in the trigger. Disconnect and reconnect, approving them, to enable it.

6. Disconnecting

You can disconnect HubSpot at any time, directly from Clareefai.

  1. 1

    Open CRM Import

    Go to Promoters, then CRM Import, and select HubSpot. The connected state shows your Hub ID.

  2. 2

    Disconnect

    Click Disconnect and confirm.

What happens when you disconnect

  • Your stored HubSpot credentials are deleted from Clareefai immediately.
  • Contacts you already imported stay in Clareefai — they are your data, and disconnecting does not remove them.
  • Active workflows with a HubSpot trigger stop watching your CRM, and resume when you reconnect.
  • You can reconnect at any time, and you will be asked to approve permissions again.
  • You can also remove Clareefai from the connected apps settings inside HubSpot, which has the same effect.

7. Troubleshooting

Clareefai says HubSpot is not connected, but I connected it.
The connection was removed on the HubSpot side — either the app was uninstalled or its access was revoked. Reconnect from Promoters, then CRM Import.
A feature is unavailable, or an action tells me to reconnect.
The optional permission that feature depends on was declined during authorization. Disconnect and reconnect, approving the permission on the HubSpot screen.
I cannot select a contact in the import table.
The contact has no email address, or it has already been imported into Clareefai. Both cases are labelled directly on the row.
Not all of my contacts appear in the table.
A single fetch loads up to 5,000 contacts. If your account has more, use the search box to find the specific people you want to import.
My workflow did not start when the deal was won.
Check that the workflow is active, that the deal has an associated contact, and that the optional deal permissions were granted when you connected. Checks run every few minutes, so allow a short delay. The run and its outcome appear under Automations, then Runs.

8. Support

Still stuck, or want something the integration does not do yet? We answer every message and read every feature request.

support@clareefai.comContact usPrivacy policy