Gravity Forms HubSpot - WordPress Plugin

A Practical Guide to Configuring Gravity Forms HubSpot to Send Form Leads to Your CRM

Gravity Forms HubSpot is not just there to "connect a CRM to a form." Its real job is to turn a WordPress form submission into a controlled data flow: a visitor submits a request, Gravity Forms stores the entry, the add-on sends the required fields to HubSpot, and the sales or marketing team sees the contact, source, and submission context without any manual copying.

In this guide, we are not covering the marketing pitch. We are walking through the practical setup: what to check before installation, how to connect your HubSpot account, how to create a feed, which fields to map first, how to use conditional sending, how to verify the result, and how to troubleshoot a case where the entry exists in Gravity Forms but the contact never appears in HubSpot.

This guide is written for site owners, marketers, WordPress admins, and developers who need to configure the integration properly. It does not cover license purchases or workarounds for product limitations. It assumes Gravity Forms and the add-on are already available in your installation, and that your goal is to set up data transfer safely and know where to look if the workflow breaks.

How the form, feed, and HubSpot contact work together

Gravity Forms HubSpot has one important architectural detail: the integration is built around a feed. A feed is a processing rule for a specific form that tells the add-on where to send the data, which Gravity Forms fields map to HubSpot properties, and under what conditions the submission should be sent. So simply activating the add-on and connecting your account is not enough. Until an active feed exists for a form, nothing will be sent to the CRM.

A typical sequence looks like this: a user opens a page with a form, fills out the fields, submits the form, Gravity Forms validates the data, stores the entry, and runs the add-on feed. Gravity Forms HubSpot then builds the submission object for HubSpot, includes the contact data, page context, and, if available, the tracking cookie and visitor identifier. HubSpot either creates a new contact or updates an existing contact with the same email address.

This logic is useful for sites where inquiries need to land in the CRM immediately: consultation requests, demo requests, quote requests, contact forms, lead magnets, event registrations, and service inquiries. The visitor stays in a familiar WordPress form, while your team receives structured data in HubSpot.

What the add-on actually sends

In the basic setup, the add-on sends the contact data you mapped in the feed. The email field is required for mapping because HubSpot uses it to create or update the contact. You can also send first name, last name, phone number, company, job title, product interest, consent to data processing, and other contact properties if they exist in HubSpot and are allowed for use in forms.

The official documentation notes that additional HubSpot properties are pulled into the feed settings, but the list is cached for about an hour. That means a newly created custom property may not appear in the dropdown right away. For that case, the add-on includes an option to clear the custom field cache.

Why this is not the same as a native HubSpot form

Gravity Forms HubSpot does not replace your form with a HubSpot embed. You continue using your Gravity Forms form: its fields, validation, anti-spam tools, confirmations, notifications, theme styling, WordPress blocks, and additional add-ons. HubSpot receives the submission result through the integration feed. This is especially useful when the site already relies on Gravity Forms, with conditional fields, file uploads, confirmations, notifications, or an established editorial process built around forms.

If, however, you need a fully native HubSpot form with everything available in the HubSpot form editor, a different analytics model, and built-in embed code, this add-on may not be the best center of the solution. In that case, compare it with the official HubSpot WordPress plugin or direct HubSpot form embedding, while keeping the current limitations of the HubSpot form editor in mind.

Who this integration is a good fit for, and when to choose another approach

Gravity Forms HubSpot is a strong fit for sites where WordPress is already the main intake point for leads and inquiries. If your team is used to editing forms in Gravity Forms and only needs HubSpot for downstream contact management, the add-on preserves that familiar interface and removes the need for manual export.

Good use cases

• Sales lead form. The user submits their name, email, phone, company, and product interest, and the contact is automatically added to HubSpot with the correct status and lifecycle stage.
• Consultation or demo form. Conditional logic sends only submissions with commercial intent to HubSpot, while general questions stay inside WordPress or go out through email notifications.
• Marketing segmentation. Additional form fields are mapped to HubSpot custom properties so you can build lists, email campaigns, and reports later.
• Agency or B2B company site. Multiple forms send data into one HubSpot account, but each form has its own feed, owner, lifecycle stage, and property set.

When the add-on may not be the right fit

This integration does not solve every CRM automation use case. Its primary role is to send form submission data into HubSpot. If you need to create complex deals, tasks, companies, support tickets, multi-step approval workflows, or two-way data sync, you may need HubSpot workflows, Zapier, Gravity Flow, the Webhooks Add-On, custom development, or another specialized tool.

You should also be more cautious if the site already has a separate HubSpot plugin for WordPress installed. Gravity Forms documentation describes a conflict: the third-party HubSpot plugin loads a tracking script to collect data from non-HubSpot forms, while Gravity Forms relies on JavaScript submission handling and its own add-on feed. As a result, a successful form submission may never reach HubSpot, or duplicate scripts may appear on the page.

Practical takeaway: if your goal is specifically to send Gravity Forms submissions into HubSpot, use the official Gravity Forms HubSpot Add-On as the primary method and do not duplicate collection for the same form with a separate HubSpot WordPress plugin unless you have a clear reason.

What to check before installation and connection

Preparation matters for a reason. Most CRM integration issues are not caused by the connect button itself. They usually come from incomplete field planning, conflicting scripts, caching, cookie consent, or assumptions about behavior the add-on was never meant to handle.

Access and environment

Start by making sure you have WordPress admin access, access to Gravity Forms add-ons, a working HubSpot account, and permission to authorize the application in HubSpot. Your WordPress environment should not block outgoing requests to the HubSpot API. If the site runs behind a strict firewall, proxy, or security plugin, keep the WordPress system status and server logs close at hand from the start.

The official add-on page lists system requirements that follow WordPress recommendations: a current version of WordPress and supported versions of PHP and MySQL. This guide does not tie itself to specific versions as if they were permanent facts, but before deployment you should still verify the product page and changelog. Integrations with external APIs are especially sensitive to outdated add-ons.

Plan your data before you build the feed

Before connecting anything, it helps to create a small mapping table: which fields exist in the form, which properties should exist in HubSpot, which ones are required, which are optional, and which should remain only in the Gravity Forms entry. This saves time during mapping and reduces the chance of sending messy or unsupported values into the CRM.

Script conflicts, caching, and cookie consent

If the site uses JavaScript optimization, deferred loading, aggressive caching, Cloudflare Rocket Loader, a cookie banner, or tracking blockers, identify your form pages upfront as areas that need separate testing. Gravity Forms documentation links issues with the hubspotutk cookie to caching, optimization, cookie opt-in, and browser settings. That does not mean you need to disable caching across the whole site. In most cases, it is enough to exclude the form page or the HubSpot script from aggressive processing and then retest.

Installing the add-on and connecting your HubSpot account

After installing and activating Gravity Forms HubSpot, go to the WordPress admin area. In a standard setup, the path starts under Forms, then Settings, then the HubSpot tab. There you will find the button for connecting your HubSpot account. After switching to HubSpot, you need to grant access, return to WordPress, and confirm the connection status.

How to tell the connection worked

In the add-on settings, you should see a status showing that the site is signed into HubSpot. In recent versions, the changelog also mentions displaying the Portal Id for the connected account, which helps you avoid mixing up a production HubSpot portal with a test or client account. If you work with multiple HubSpot accounts, always verify the portal after connecting, otherwise your test submissions may be going to the wrong place.

At this point, do not assume the integration is already working end to end. The connection only means WordPress has permission to communicate with HubSpot. Data from a specific form will only start reaching the CRM after you create and enable a feed.

If the connect button does not appear

The documentation describes a specific scenario where the connect button may not appear if a refresh token was not received or cannot refresh the access token. The add-on logs for that case include a recognizable message about a missing refresh token. The official workaround is to open Forms > Settings > HubSpot, add the parameter &gf_display_connect_button=1 to the URL, press Enter, and reconnect the account.

Use that technique only as a recovery step, not as part of normal setup. If the issue keeps coming back, check the changelog, the add-on version, HubSpot API availability, and contact support with the relevant logs.

Creating the feed: fields, owner, lifecycle, and submission conditions

The feed is the core of the Gravity Forms HubSpot configuration. This is where you decide how the WordPress form should be represented in HubSpot: what the created HubSpot form is called, which lifecycle stage the contact gets, who it is assigned to, which properties are filled in, and under what conditions the submission should reach the CRM at all.

Where to create the feed

Open the form you want under Forms, go to its settings, choose HubSpot, and click Add New. Do not create one generic catch-all feed for every form just in case. Different forms usually collect different data, serve different goals, and should be sent to HubSpot under different conditions.

Feed name and HubSpot Form Name

Give the feed a clear name, such as "Demo request to HubSpot" or "Consultation leads." The HubSpot Form Name field matters because the add-on creates or updates a form in HubSpot for this feed. The documentation includes a warning: the generated HubSpot form should not be manually edited or deleted. If a marketer changes it directly in HubSpot, the relationship with the feed can become unpredictable.

Lead Status and Lifecycle Stage

Lead Status and Lifecycle Stage let you classify the contact right away. For a basic contact form, more neutral values may be appropriate. For a demo request, choose the status the sales team actually uses. Do not force an overly advanced lifecycle stage just because the field is available. Your CRM should reflect the real quality of the contact.

Contact Owner

The feed can leave the contact unassigned, assign a specific HubSpot user, or assign the owner conditionally. Conditional assignment is useful when one site serves multiple regions, business lines, or account managers. But keep a current HubSpot limitation in mind: Gravity Forms documentation notes that the Contact Owner section may be hidden for the connected account if HubSpot does not allow creating or updating a form with the owner field. So a missing owner field in the feed does not always mean the WordPress interface is broken.

Map Contact Fields

Mapping is the most important step. Email is required. Choose the rest of the fields based on business meaning. You do not need to send every form field into HubSpot just because it exists. If a field is only needed for local processing, internal notifications, or a one-time comment, it can stay in the Gravity Forms entry.

Choice fields follow a strict practical rule: the values in Gravity Forms must match the options in the HubSpot property. The documentation explicitly states that for HubSpot fields with selectable options, the values must exactly match the values in the Gravity Forms choice based field. This is especially important for checkboxes, radio buttons, and dropdowns.

Add Additional Contact Fields and property caching

If you create a custom HubSpot property such as "Product interest," "Budget range," or "Preferred service," it may appear in the additional contact fields block. But the list is not refreshed instantly: Gravity Forms caches custom fields for about an hour to avoid hitting API limits. If you just created the property in HubSpot and do not see it in WordPress, go to Forms - Settings - HubSpot and use Clear Custom Field Cache.

Enable Conditional Logic

Conditional sending is especially useful when one form handles different kinds of inquiries. For example, commercial requests may go to HubSpot, while technical support requests stay in a help desk or simply go out by email. If the Enable Conditional Logic checkbox is off, every successful submission will be sent to HubSpot. If it is on, the feed will run only when the conditions match.

Quick check after saving: open the form's feed list and make sure the required feed is enabled. If the feed is disabled or the condition does not match, the entry will be saved in Gravity Forms, but nothing will be sent to HubSpot.

Configuring list values, consent, and custom properties

The weakest point in CRM integrations is usually not the connection itself. It is data quality. HubSpot works best when contact properties are filled in consistently. Once the CRM starts receiving multiple variations of the same value, extra spaces, duplicate Russian and English labels, or random form labels, your lists and automations become messy very quickly.

Radio Buttons, Drop Down, and Checkbox

For Radio Buttons, the documentation recommends enabling Show Values in the Gravity Forms field settings and setting the off choice value to false, or leaving it blank if the field is not required. For Drop Down, you can use the placeholder appearance field setting for the off choice, or also enable Show Values and set the value to false. The goal is to make sure HubSpot receives the expected value instead of a random label or an empty string in the wrong format.

For checkbox and multi-choice fields, decide in advance whether the HubSpot property should support multiple values or only one. Do not try to cram a complex questionnaire into a single text field if the team will later filter contacts by interest. It is better to create separate properties or a list with predictable values.

Consent Field

Gravity Forms HubSpot supports mapping for the Consent Field. That matters for forms that require explicit consent. But technical support for the field does not replace the legal setup of your consent text, privacy policy, or data processing rules. Use the Consent Field as a structured source of consent data, not as a decorative checkbox.

What is not supported in mapping

The documentation states that mapping to advanced choice based fields such as Quiz, Poll, and Survey is not supported. In practice, that means you should not design the integration as if quiz or survey results will automatically become standard HubSpot choice properties. If you need to transfer that kind of data, look at a separate handling method: hidden fields, simple choice fields, Webhooks, custom code, or a CRM workflow.

Safe extension through the official filter

Most sites do not need code. But for developers, the official gform_hubspot_submission_data filter allows you to modify the submission data before it is sent to HubSpot. Gravity Forms documentation provides an example of how to pass Consent Field data into HubSpot's legal consent structure. That approach is reasonable if you understand the form structure and keep the code in a child theme, a custom functions plugin, or Code Snippets.

The example below is not a universal legal setup. It is simply a safe pattern showing how to avoid editing the plugin core and keep the customization small. Before using it, replace the consent field ID with your own and test it on a copy of the form.

add_filter( 'gform_hubspot_submission_data', 'site_send_hubspot_consent', 10, 4 );
function site_send_hubspot_consent( $submission_data, $feed, $entry, $form ) {
    // Replace 4 with the Consent Field ID in your form.
    $consent_value = rgar( $entry, '4.1' );
    $consent_text  = rgar( $entry, '4.2' );

    $submission_data['legalConsentOptions']['consent']['consentToProcess'] = ! empty( $consent_value );
    $submission_data['legalConsentOptions']['consent']['text'] = $consent_text;

    return $submission_data;
}

The validation is simple: submit a test form, open the HubSpot Add-On logs, and check the contact record in HubSpot. If the consent structure does not appear or HubSpot returns an error, remove the snippet and go back to standard mapping. Do not leave custom code enabled if you cannot clearly explain what data it is changing.

Practical example: a demo request sent to HubSpot

Let us look at a real B2B scenario. A product page includes a "Request a Demo" form. The goal is for HubSpot to create or update a contact and fill in the first name, email, phone, company, product interest, lifecycle stage, and owner. At the same time, only submissions where the user selected commercial intent should go into the CRM, while general questions should not.

Goal

After the form is submitted, the manager should see the contact in HubSpot, understand which product the user is interested in, know which page the form was submitted on, and see who is responsible for follow-up. The Gravity Forms entry should retain a complete copy of the submission for backup verification.

Preparation

• In Gravity Forms, create a form with the fields Name, Email, Phone, Company, Product Interest, Message, and a Consent Field.
• In HubSpot, create or identify the property for product interest, and make sure its options match the values in Gravity Forms.
• Make sure Gravity Forms HubSpot is connected to the correct HubSpot portal.
• If the site has tracking cookie issues, exclude the form page from aggressive JavaScript optimization.

Setup steps

1. Open the form in WordPress and go to Settings - HubSpot.
2. Create a new feed through Add New and name it clearly enough that its purpose is obvious.
3. Set the HubSpot Form Name, for example Demo Request, and do not manually edit the generated form in HubSpot.
4. Select an appropriate Lifecycle Stage if it matches your CRM process.
5. Configure the owner: leave it blank, select a specific user, or enable conditional assignment by product or region.
6. Map email, name, last name, phone, company, and the custom product-interest property.
7. Enable Enable Conditional Logic if only commercial requests should go to HubSpot.
8. Save the feed and make sure it is active.

How to verify the result

Open the form page in a private browser window. Submit a test request using a unique email so it cannot be confused with an existing contact. After submission, check three places: the Gravity Forms entry, the add-on logs with diagnostics enabled, and the contact record in HubSpot.

If the contact is created but some fields are empty, the problem is almost always the mapping or the field values. If the entry exists but nothing shows up in HubSpot, check whether the feed is active, whether conditional logic ran, and whether the logs show any API errors. If the contact is being updated in an unexpected way, verify the email and the cookie relationship: HubSpot uses the email address as the primary contact identifier, and the tracking cookie helps link the submission to a known visitor.

A nuance during repeated testing

The feed documentation highlights an important detail: the first submission from a user creates a customer record, a repeat submission with the same email updates that record, and a new record is created only when a new email is used. Each browser session is also tied to a cookie, so when you are quickly testing multiple "different" users, it is best to use different email addresses and a fresh browser session. Otherwise, it may look like the add-on is incorrectly merging contacts when in fact it is following HubSpot's expected logic.

Updates, background processing, and maintaining the integration carefully

A CRM integration is never truly a one-time setup. HubSpot changes its API, Gravity Forms updates its Add-On Framework, and the site may later receive a new cache plugin, cookie banner, or security rules. That is why Gravity Forms HubSpot should have a lightweight maintenance routine: understand what changed before an update, verify the feed after the update, and review any custom filters separately if custom code is in place.

Why the changelog matters for this specific add-on

The HubSpot Add-On changelog contains more than cosmetic fixes. It includes the move to the HubSpot Marketing Forms v3 API, changes to developer filters, fixes for the owner field, lifecycle stage, token refresh, field mapping, and duplicate tracking scripts. For a typical admin, that translates into a simple rule: if the owner field disappears after an update, the feed stops saving, or a custom property behaves differently, check the changelog first instead of changing the form blindly.

Pay special attention to sites where a developer added snippets on gform_hubspot_form_object_pre_save_feed. That filter was officially updated for the new HubSpot form object structure. Old code may still look "fine" in the snippet editor while breaking feed saving or sending an invalid structure to HubSpot. A safe test is to temporarily disable the snippet on staging, save the feed, and submit the form using a new email address.

Background feed processing and user expectations

The add-on changelog includes support for async background feed processing. The point of that logic is to avoid making the user wait for every external API call when the work can be handled in the background. That is a benefit for the site owner, but it changes troubleshooting expectations: the contact may not appear in HubSpot at the exact millisecond the user sees the confirmation. It may appear after the background task has been processed.

If the form is saved but HubSpot updates with a delay, do not assume something is broken too quickly. Check the WordPress system status, cron/background tasks, Gravity Forms core logs, and HubSpot Add-On logs. If cron is disabled, loopback requests are blocked, or a security plugin interferes with background requests, the add-on may not be able to run the feed when expected.

Post-update mini checklist

1. Review the Gravity Forms HubSpot Add-On changelog and note changes related to the API, feed settings, owner, lifecycle, field mapping, and tracking script.
2. On a test form, submit a request using a new email and make sure the entry is saved.
3. Open the feed and verify that email mapping, custom properties, owner, and conditional logic are still in place.
4. Check the contact record in HubSpot and confirm that values have not turned into empty strings or invalid list options.
5. If the site uses snippets for the HubSpot Add-On, verify them against the current filter documentation.
6. After troubleshooting, disable logging and delete the logs if they contain personal data from test submissions.

Useful habit: keep a short feed map next to the site documentation: form, purpose, HubSpot Form Name, required fields, custom properties, submission conditions, and the responsible owner. That way, updates and CRM integration audits take minutes instead of turning into an investigation.

Verifying the result after setup

Verification should be a separate phase, not just a quick glance at a green success message. A CRM integration affects data, marketing, sales, and privacy, so you want to confirm that every step in the chain worked correctly.

Check in Gravity Forms

Open the form entry and compare the stored values with what you expected to send. If the entry was not saved, the problem is not in HubSpot but in the form itself: validation, anti-spam, JavaScript, a theme conflict, or blocked submission. If the entry was saved but the feed did not run, move on to the HubSpot feed settings.

Check in HubSpot

In HubSpot, search for the contact by the email you used in the test. Check the populated properties, lifecycle stage, owner, and activity. If you expected to see a page visit or a link to previous activity, verify that the hubspotutk tracking cookie exists on the form page and that hutk is being sent in the payload.

Check the logs

Enable logging only while troubleshooting. Gravity Forms warns that logs may contain personal data in plain text, so after testing you should disable and remove them. For the test, enable logging under Forms - Settings, then turn on logging for Gravity Forms core and the HubSpot Add-On, submit the form, and review the API response.

What counts as a successful test

• The form submits without errors on the public site.
• The entry is saved in Gravity Forms with the expected values.
• The active feed runs and is not blocked by conditional logic.
• The contact can be found in HubSpot using the test email.
• The contact properties are filled according to the data map.
• The logs do not show authorization errors, rate limits, unsupported fields, or lifecycle issues.

Compatibility with caching, security, and privacy

Forms often live on pages where caching, anti-spam tools, cookie consent, analytics, JavaScript optimization, and CRM tracking all run at the same time. That is especially important for Gravity Forms HubSpot because some data is sent through the server-side feed, while some visitor context depends on the tracking script and cookies.

Caching and JavaScript optimization

Page caching itself is not a problem. Issues begin when an optimizer combines, delays, or blocks scripts in a way that prevents the HubSpot tracking script from setting the cookie before the form is submitted. If you see problems with hubspotutk, first exclude the form page from aggressive optimization instead of disabling caching sitewide.

Anti-spam and reCAPTCHA

Gravity Forms uses JavaScript for coordinated submit event handling, anti-spam checks, and duplicate prevention. That is one reason a third-party HubSpot script for non-HubSpot forms is not a reliable way to collect Gravity Forms submissions. Keep anti-spam on the Gravity Forms side, and configure HubSpot transfer through the add-on feed.

Logs and personal data

Logs are useful for troubleshooting, but they may contain personal data. So the rule is simple: enable logging, run the test, save the information you need for support, then disable logging and remove the logs. Do not leave detailed diagnostics enabled on a production site just in case.

IP address and personal data

The add-on changelog notes that the submission process sends the IP address to HubSpot if saving the submitter IP has not been disabled in the form's personal data settings. If your privacy policy requires that IP addresses not be stored or transmitted, review the form's personal data settings and align them with the site's legal requirements.

When Gravity Forms HubSpot is the right choice

Gravity Forms HubSpot is worth using if your site already relies on Gravity Forms and you want HubSpot to handle contact management, segmentation, and downstream lead work. The real strength of the add-on is not the connect button. It is the controlled feed: you choose the form, map the fields, assign the owner, set the lifecycle stage, apply conditions, and verify the result through the entry, the logs, and the contact record.

Before going live, run through a short checklist: the correct HubSpot portal, an active feed, required email mapping, matching list values, a cleared custom field cache for new properties, no conflicting non-HubSpot form collection, logging enabled only during troubleshooting, and a test submission using a new email. If all of that checks out, the integration usually becomes a predictable part of your lead handling workflow.

If you are ready to test the setup on your own site, go back to the download section and download the Gravity Forms HubSpot package, then configure it first on a single test form. That approach is safer than connecting every form on the site at once: you will see the actual fields, logs, cookie behavior, and contact quality in HubSpot before rolling it out more broadly.