Tassos Marinos Developer of Joomla Extensions

Integrate HubSpot with Convert Forms

Published in Convert Forms
Updated 22 Dec, 2023

Are you interested in adding users to your HubSpot lists through your Joomla forms? Are you seeking a solution to integrate Convert Forms with HubSpot and automate lead generation effortlessly? With the HubSpot app for Convert Forms, you can easily subscribe users in your HubSpot account each time someone submits your form.

This tutorial will guide you through using and configuring the HubSpot addon in Convert Forms.



To use the HubSpot integration, there are a few requirements you need to meet, listed below:

  • Ensure you have Convert Forms Pro installed. You can easily upgrade to Pro if you're currently in the Free version
  • The "Convert Forms - Apps - HubSpot" plugin is enabled.
  • Your form includes an Email field.

Setting Up HubSpot Task

To set up the HubSpot task and sync your submissions to the HubSpot service, go into your form, and follow the steps listed below:

Select App

From within your form, click on Tasks > CREATE YOUR FIRST TASK.

Create First Task

On the modal that will open, select the HubSpot task.

Select HubSpot Task

Select New Submission under Trigger and Add/Update Contact under Action on the next screen, and click CONTINUE.

Select HubSpot Trigger and Action

Create Connection

A connection is essential to be able to connect to a 3rd-party service, such as HubSpot. Let's see how to create a new connection that will allow us to connect to HubSpot.

On the next step, click SIGN IN to create our HubSpot connection.

HubSpot Create Connection Sign In

To create our connection with HubSpot, Click ADD CONNECTION to get started.

HubSpot Create New Connection

Get your HubSpot API Key

Before connecting to HubSpot, we need to create a HubSpot API Key. To grab your API Key, follow the steps listed below:

To obtain your HubSpot API Key you need to log into your HubSpot Account, select your account > on the top right on your Name > Profile & Preferences > Select Integrations from the left menu sidebar > Integrations > Private Apps > Click on Create a private app.

HubSpot Create Private App 1

Once you have clicked the button, a new screen will appear to create the new private app. Start by entering a name under "Name" and click on the "Scopes" tab.

HubSpot Create Private App 2

In this step, you must enter all required scopes as seen below:

  • crm.objects.contacts.read
  • crm.objects.contacts.write
  • crm.lists.read
  • crm.lists.write

Once you have added all scopes, click on Create app.

HubSpot Create Private App 3

Your private app is now created and you can now obtain your HubSpot API Key.

To get your API Key click on "View access token" and copy it.

HubSpot Create Private App 4

 Now that we have created our HubSpot API Key, we can continue setting up the connection with HubSpot. Enter a connection name and paste your HubSpot API Key in the fields Connection Name and HubSpot API Key, respectively. Then click ADD CONNECTION.

HubSpot Setup New Connection

The connection has been added, and you can close the connections window.

HubSpot New Connection Setup OK

If you see the "Connection added" message, your connection with HubSpot has been established, and you can continue with the next step. If you see any error message, please review your API Key.

Select the newly created connection from the list and click CONTINUE.

HubSpot Select New Connection

Ensure that your newly created HubSpot connection is selected in the dropdown.

Tip: Connections are reusable across your Tasks; read more on the Working with Tasks documentation page.

Setup Action

After you've set up the trigger, action, and connection, it's time to set up the action itself and define what information to send to HubSpot. In this step, you can view all available settings and map each option with a fixed or dynamic value using Smart Tags.

Setup Action HubSpot Task

Let's see all available settings:


Select the list to which all subscribers will be saved in your HubSpot account. A complete list of all your HubSpot lists will be available, and choose from any form field, or Smart Tag.

Update existing subscriber

Enable to update existing subscribers' information on your HubSpot account. Disabling this will result in your users seeing an error message when the form is submitted, which prevents already subscribers from re-subscribing to your lists.

Email Address

Select the email address of the submitter. This is the user that will be subscribed to your HubSpot list. Choose the Email field in your form.


HubSpot provides Properties, which allows you to store additional information when a subscriber is saved on your HubSpot account, such as their name, age, company info, and more!

When you click on the Properties dropdown, you will automatically be shown a list of existing custom fields from your HubSpot account, and you will be able to map them with an existing form field, or Smart Tag.

To create or edit your HubSpot custom fields please click here: How to create and use HubSpot properties.

That's it! Your custom field can now be used in your HubSpot task.

Add Conditional Logic

Conditional logic makes it possible to run tasks only if specific criteria are met, like a user’s email address matching a certain domain, the user being associated with a certain Joomla User Group, or a form submission having a specific value.

While editing the HubSpot task, go to the Setup Action step and scroll down to the Conditional Logic section to set up Conditional Logic. Here's where you define all the rules the task should meet to run.

For example, let's say we need to sync submissions to HubSpot, only if the email is coming from a specific domain: @domain.com.

  1. Click to enable the Run this task when certain conditions are met.
  2. Click Add Your First Condition.
  3. Select the Email field in the Trigger dropdown.
  4. Select Contains in the Operator dropdown.
  5. Enter @domain.com in the value. Replace this with your domain name.

The condition should look like this:

HubSpot Task Conditional Logic Example

You can read more on Conditional Logic on the Working with Tasks documentation page.

Activate Task

The final step is to enable our task. To do so, click the toggle on the dialog’s top right corner, as shown in the screenshot below.

Enable Task HubSpot Task

Finally, click Save to save the task, close the dialog, and then click Save from the top right corner of the form builder to save the changes on the form.

Congratulations! You’ve successfully created a form that syncs new submissions to HubSpot!

Setting Up HubSpot Campaign (Deprecated)

This method uses the soon-to-be deprecated Convert Forms Campaigns, which requires you to create an HubSpot campaign, configure it and assign it to your form. We suggest you use the new tasks way of integrating HubSpot with Convert Forms by clicking here.

To get started follow the steps below:

  • Navigate to Components > Convert Forms > Addons
  • Click the Cog button for the HubSpot Addon. A popup will appear where you can enable the addon.

hubspot convert forms addon

  • Click on the Status and select Enabled.
  • Now you can click on Save & Close button to save the enabled addon.

2. Campaign Setup

To setup a Campaign with HubSpot, follow the steps below.

hubspot campaign convert forms

  • Navigate to Components > Convert Forms > Campaigns
  • Create a new Campaign by clicking New
  • Type a name for your Campaign. This name can not be seen by anyone else but you.
  • For the Sync Leads > Choose Service selectbox choose HubSpot. If you can not find the HubSpot option then you do not have the HubSpot Addon installed and activated. In that case, please go back to the top of the article and see how to install the mandatory addon.
  • Save the Campaign for the HubSpot API Key field to show up.

HubSpot API Key

To grab your HubSpot API Key click here

Finally, now that you have the HubSpot API Key, you can Save & Close this Convert Forms Campaign.

3. Email & Name Fields


For a Convert Form to successfully store an email address to your HubSpot account it needs to have an email field. This field is already set up at the time of creating the form and you don't have to change its input value as it is already configured for you.

convert forms email field


HubSpot offers by default one field specifically for the contact's first name. To use that field you should create a field named firstname. See the screenshot below to understand where to set it up.

hubspot first name

You can use this field as a fullname option as well but we recommend that you create a field named lastname to store your contact's last name. If you would like to store more name-related fields like middle name you need to create the field through your HubSpot account. This way you would be creating essentially a custom field. See next how to use HubSpot's custom fields with Convert Forms.

4. HubSpot Custom Fields

HubSpot offers custom fields to collect more types of data for each of your contacts. We can also use these custom fields in a Convert Form for a more efficient data gathering and by extension, a more efficient campaign. Furthermore, HubSpot already provides a wide collection of fields that you can use to characterize your contacts. Let's see where to find them and how to use them.

4a. Find the HubSpot fields

First you need to navigate to your HubSpot Account, click "Contacts" in your HubSpot Account's main menu and then click "Actions" > "Edit Properties".

hubspot custom fields

In the Properties Screen you can see all the fields that can be used already. To use any of these fields you need to find its internal name. To do that, click on any of them, on the popup sidebar that will appear, click on the </&dt; Icon next to the name to reveal the internal name. Then copy the internal name from the popup window as seen below:

hubspot custom field name

4b. Create a custom HubSpot field

Apart from the already available HubSpot fields, you can also create fields of your own. To do that follow the steps below.

  • Click the "Create property" button at the top right of your screen.

hubspot new custom field

Type the label of the field and click Next.

hubspot new custom field setup

Select the field type. Convert Forms can accommodate all of the field types listed there apart from the File Upload type and the Datepicker type. Click Create to save the property.

hubspot new custom field setup

4c. An example Convert Form with HubSpot custom fields

As you can see in the screenshot below we have setup an example Convert Form using HubSpot's custom fields. In this example we use HubSpot's city field and an age field which we created through HubSpot.

hubspot custom fields city

hubspot custom fields age

5. Assign form to Campaign

Of course don't forget to assign the form to our newly created Campaign! See the screenshot below to understand where to assign it.

hubspot convert forms assignment