Hubspot CRM

Estimated reading: 7 minutes

Overview

HubSpot is a CRM with marketing, sales, and service hubs. AFI connects to HubSpot via a Private App access token and creates contacts (and on Pro, records in any HubSpot object plus an upsert-and-deal combined flow) from every matching form submission, WooCommerce order, or user signup.

Supported actions

Create New Contact (Free + Pro); adds a new contact in HubSpot, populating standard and custom contact properties from your mapped fields.
Create New Record (Pro); create a record in any HubSpot object (Contacts, Companies, Deals, Tickets, or custom objects).
Upsert Contact + Create Associated Deal (Pro); match an existing contact by email (or create one if missing) and create a deal associated with that contact in a single step.

AFI Pro adds richer field mapping for HubSpot; additional sender-plugin field types (phone, date, dropdown, hidden, custom fields) are exposed in the mapping panel, and your custom HubSpot properties become available for mapping alongside the standard fields.

Quick reference

Need to…	Do this
Send leads to HubSpot	Create integration → Sender plugin → HubSpot CRM → Create New Contact → map email + name + properties.
Capture UTM source / GCLID	Enable Send UTM Variables in AFI > Settings > General, then map `{{utm_source}}` / `{{gclid}}` onto custom HubSpot contact properties.
Create a deal alongside the contact	Use Pro’s Upsert Contact + Create Associated Deal task; one form submission writes the contact and the deal at once.
Push to a custom object	Use Pro’s Create New Record task, then pick the object type.
Map custom contact properties	Custom HubSpot properties surface in the mapping dropdown automatically once the Private App token has the `crm.objects.contacts.write` scope.

Heads up: HubSpot Private App tokens are scope-gated; the token you generate must include the read/write scopes for each object you intend to use. If a custom property doesn’t appear in AFI’s mapping dropdown, the most common cause is a missing scope or an unpublished property in HubSpot. The full setup walkthrough (with screenshots) is below.

Authentication

First, you need to connect your Hubspot CRM account by authorizing it on the plugin’s settings page.

Go to AFI > Settings > General where you’ll see a list of all the supported platforms. Hubspot, turn it on, and click the Save Changes button at the bottom.

You’ll see a Hubspot CRM tab at the top. Click on it and follow the steps to complete the authorization process.

In HubSpot, go to Settings > Integrations > Private Apps.
Click on the Create a private app button.
Go to the Scopes tab, and choose the permissions you need. For example, if you want the plugin to create Companies and Contacts, make sure both read and write permissions are enabled for them.
Click on Show token and copy the key that appears.
Paste in AFI > Settings > Hubspot CRM input box and Save.

Create New Integration

After saving your credentials on the settings page, you can begin creating a new integration. Access the New Integration page by clicking on Add New under the AFI menu.

Title

A default title with an auto-incremental number will be generated. However, you can rename it to a name that relates to the specific task. This will enable you to promptly identify the correct integration, particularly when multiple integrations are in place.

Trigger

Choose the desired sender form from the Form Provider dropdown, such as Contact Form 7, Gravity Form, or Elementor Pro Form, that you wish to link. Once selected, all forms constructed under that provider will be retrieved and automatically displayed in the Form/Task Name dropdown. Proceed to select the form that you intend to integrate.

Action

Select Hubspot CRM or Hubspot CRM [PRO] based on your AFI subscription.

Map Fields

In this section, you’ll see two dropdown menus: one for selecting the Owner and another for selecting the Object.

Owner refers to the user in HubSpot that will be associated with the data (e.g., the HubSpot user who will own the new contact or deal). Object refers to the type of HubSpot data you want to create or update (e.g., Contacts, Companies, Deals, etc.).

After selecting the Owner and Object, the plugin will automatically fetch and display all the fields associated with the chosen object. These fields represent the data points in HubSpot, such as first name, last name, email, company name, deal amount, etc.

For each field listed under the selected object, you need to map the corresponding data from your form. For example, if your form collects an email address, you would map the form’s email field to the Email field in HubSpot. Only fill in the necessary fields that are crucial for your integration. You can leave other fields empty if they are not needed.

Once you have completed mapping all the required fields, click Save to finalize the integration. This step ensures that the plugin knows how to transfer the form data into HubSpot when a visitor submits the form on your website.

Common issues & fixes

If a HubSpot integration stops working or doesn’t create records, work through these in order:

Re-check Private App scopes. In HubSpot > Settings > Integrations > Private Apps, open your AFI app and confirm the scopes match the tasks you’re using (contacts.write for Create Contact, plus the relevant object scope for Create Record).
Rotate the access token. If the token was regenerated in HubSpot, paste the new token in AFI > Settings > HubSpot CRM and Save.
Confirm the property exists and is internal-name-matched. HubSpot custom properties are mapped by their internal name (lowercase, underscored), not the display label. Open the property in HubSpot to see its internal name.
Check property type compatibility. Mapping a free-text field onto a HubSpot dropdown property fails silently; the value must match one of the dropdown options. Use Conditional Logic or a smart-tag transform to coerce the value.

Specific symptoms

401 Unauthorized. The Private App token is invalid or revoked. Regenerate it in HubSpot and re-paste it in AFI.
403 / scope error. The token doesn’t include the scope needed for the action you’re calling. Edit the Private App in HubSpot and add the required scope.
Custom properties missing in mapping dropdown. Click the refresh icon next to the property dropdown in AFI to re-fetch from HubSpot. New properties created after the integration was set up need a re-fetch.
Duplicate contacts created. HubSpot deduplicates by email automatically; if you’re still seeing duplicates, check that the email field is mapped and isn’t blank.

Notes & caveats

Use Private Apps, not OAuth. AFI authenticates against HubSpot via a Private App access token. Generate one in HubSpot > Settings > Integrations > Private Apps.
Keep the Private App owner active. The Private App belongs to a HubSpot user; if that user is removed from the HubSpot portal the token can be revoked. Create the app under a service-style account when possible.
Pro adds field-mapping depth, not new task types beyond the two Pro tasks above. The free Create New Contact task is the same on Pro; Pro adds two additional tasks (Create New Record, Upsert Contact + Create Associated Deal) plus richer field mapping across all tasks.