Skip to main content

HubSpot CRM IntegrationRevised 3.13.18+Pro

This guide assumes you have a HubSpot account already.

If you're using the old Legacy API Key version of the HubSpot integration, be sure to switch to this updated integration before. November 30, 2022. After that date, API calls made with the old API keys on or after November 30, 2022 will return 401 errors.

For existing HubSpot users (set up before 4.0.1 or 3.13.18), please see the special update instructions.

This documentation page assumes you have read over the CRM Integration Overview. If you have not yet read it, please do so now. We also assume that you have a HubSpot account already. This integration requires that you have Freeform Pro. If you currently have Freeform Lite, you can purchase an upgrade to Freeform Pro.

Please note this is a complete integration between Freeform and HubSpot and should NOT be used along with HubSpot's "Collected Forms" javascript-based feature. Otherwise, you may observe unintended behavior.

​Compatibility

HubSpot integration includes support for field mapping to standard and custom fields from all 3 endpoints listed below (of text/number string type only). It maps data to Deals (optional), Contacts and Companies API endpoints.

​Duplicate Check & Update

A duplicate check on records is done in the following way:

  1. Check whether the Contact already exists:
    • Check against Email address as the identifier.
    • If there's a match, update the Contact with new values, where supplied.
    • If no match, create a new HubSpot Contact.
  2. Check whether the Company already exists:
    • Check against Company domain name, which is automatically generated by HubSpot from the Contact email address domain name.
    • If there's a match, update the Company with new values, where supplied.
    • If no match, create a new HubSpot Company.
    • If a new Contact was created, link the contact to the Company.
  3. Create new Deal.
    • Attach the Deal to existing or newly created HubSpot Company and Contact.

​Setup Instructions

1

​Create & get Private App token from HubSpot

  • Go to HubSpot and log into your account.
  • At the top right corner, click on the profile icon and select Profile & Preferences.
  • Click on the Integrations left navigation item, and then click on Private Apps.
  • Click the Create a Private App button.
  • In the next page, update the name and other information for the app as you wish.
  • Click on the Scopes tab at the top.
  • Then click on the CRM scope category and select Write and Read for:
    • crm.objects.companies
    • crm.objects.contacts
    • crm.objects.deals
  • Click the orange Create app button at the top right corner of the page.
  • When the modal loads with the private app token, copy that newly created token.
2

​Set up Integration on your site

  • Go to the CRM section in Freeform Settings (Freeform > Settings > CRM).
  • Click the New CRM Integration at the top right.
  • Select HubSpot (v1) from the Service Provider select dropdown.
  • Enter a name and handle for the integration.
  • Paste the HubSpot Private App token into the Private App Token field in Freeform.
  • Additional configuration:
    • IP Address Field (optional)
      • If you want to have the user's IP address sent over to the Contact in HubSpot, you can specify the custom HubSpot Contact field handle to receive it.
    • Append checkbox group field values on Contact update?3.2.4+
      • If a Contact already exists in HubSpot, enabling this will append additional checkbox group field values to the Contact inside HubSpot, instead of overwriting the options.
    • Append checkbox group field values on Company update?3.2.4+
      • If a Company already exists in HubSpot, enabling this will append additional checkbox group field values to the Company inside HubSpot, instead of overwriting the options.
  • At the top right corner of Freeform page, click Save button.
3

​Verify Authorization

  • After the integration is saved, it'll return you to the list of CRM integrations.
  • Click into the newly created integration.
  • Confirm that there is green circle with Authorized in the middle of the page.
Finished!

​2022 Private Key Update Instructions

On June 1, 2022, HubSpot announced that the API Key approach for integrations would be retired on November 30, 2022 in favor of the Private App approach. This is a change that will break existing integrations, and requires an update to Freeform in order to fix the connection. API calls made with API keys on or after November 30, 2022 will return 401 errors.

On August 23, 2022, we released Freeform 4.0.1 to address this. For any existing users of this integration (set up before 4.0.1 or 3.13.18), please follow the below instructions to upgrade your connection:

  1. Update to Freeform 4.0.1 or greater.
  2. Go to the CRM section in Freeform Settings (Freeform > Settings > CRM) and create a new integration.
  3. Follow the steps above in the Setup Instructions.
  4. Open up all forms using HubSpot and update the integration to be the new HubSpot one you just created (and reapply mapping table).
  5. Test out your form(s) to ensure things are still working smoothly.
  6. Remove the old legacy HubSpot integration.
Page Feedback