Documentation

HubSpot Integration Guide

Connect your HubSpot account to Clareefai to import contacts as promoters, push referrals back into your pipeline, and target campaigns with the lists you already use.

Last updated: July 28, 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 unlocks writing back to HubSpot and targeting campaigns — you can decline it and the connection still works.

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.contacts.write

    Create a contact in HubSpot when you push a referral. Without it, pushing referrals is unavailable.

  • crm.objects.deals.write

    Create the deal associated with a pushed referral. Without it, the referral contact is still created but no deal appears.

  • crm.lists.read

    Read your contact lists so you can use them as a survey audience. Without it, HubSpot lists do not appear when sending a survey.

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. Pushing referrals to HubSpot

When a promoter delivers a warm referral, you can send it straight to HubSpot so your sales team works it in the pipeline they already live in.

  1. 1

    Open the referral

    Go to Referrals in the vendor app and open the referral you want to send.

  2. 2

    Push to HubSpot

    In the CRM Integration panel, click Push to HubSpot.

  3. 3

    Confirm the result

    The panel updates to confirm the push and displays the new HubSpot Contact ID and Deal ID, giving you an audit trail from advocate to opportunity.

What gets created in HubSpot

  • One contact. Created with the referred person’s first name, last name, email address, and company.
  • One deal. Named after the referred person, placed in your default pipeline at the Appointment Scheduled stage, and associated with the contact above.

Pushing is always manual and always per referral — Clareefai never pushes anything automatically. Existing HubSpot records are never modified or deleted.

6. Targeting surveys with HubSpot lists

Reuse the segmentation you have already built. When sending a satisfaction survey or advocacy campaign, you can target your existing HubSpot contact lists instead of rebuilding the audience.

  1. 1

    Open a survey

    Go to Surveys, open the survey you want to send, and click Send.

  2. 2

    Choose CRM Import as the recipient source

    Your HubSpot contact lists appear, each with its contact count.

  3. 3

    Select your lists

    Tick one or more lists. The combined recipient total updates as you go, so you know exactly how many people you are about to reach.

This step requires the optional contact list permission. If you declined it, no HubSpot lists will appear here — disconnect and reconnect, approving it, to enable this feature.

7. 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.
  • Records Clareefai already pushed into HubSpot stay in HubSpot and are never touched.
  • 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.

8. 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.
Pushing a referral to HubSpot failed.
HubSpot rejects a new contact when one with the same email address already exists. If the referred person is already in your CRM, add the referral details to that record manually, or contact support and we will help.
The referral contact was created, but no deal appeared.
The optional deal permission was not granted, or HubSpot rejected the deal. Reconnect and approve deal access, then push again — the contact already exists, so create the deal manually if needed.
Can I change the pipeline or stage of the created deal?
Not yet. Referral deals are always created in your default pipeline at the Appointment Scheduled stage. You can move them anywhere you like in HubSpot afterwards.

9. 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