Ion Integration: HubSpot

You have two integration methods to select from when exporting data from Ion to your HubSpot instance (also known as an “Add Lead” integration): the REST API method and the Post to Web Form method. Both methods can work seamlessly with your Ion creatives. The best method for you will depend on how you like to trigger automation in HubSpot.

HubSpot: Export Data Overview

REST API

Our native integration creates/updates contacts directly in your HubSpot contact table. This method often requires less effort to update or expand your integration in the future. However, it won’t trigger form processing steps or support creation of segments filtered on form completion, since it does not submit a HubSpot form.

Post to Web Form

A Post to Web Form integration is what it sounds like: data collected in Ion is posted to a form you’ve published in HubSpot. While the customer sees a form you built in Ion (and data is saved to your Ion console), HubSpot treats it like someone completed the HubSpot form directly.

This method often requires more effort to update or expand your integration in the future, as any changes must be made to both your ion integration and your HubSpot form(s). The benefits of this method are the ability to trigger automation in HubSpot based on form completion.

Embedded Form

A reusable HubSpot form widget can be created is used to insert any HubSpot form and alter the “thank you” page destination using variables in ion’s Creative Studio. The benefits of this method are the ability to use form completion to trigger advanced logic in HubSpot and the ability to leverage progressive profiling built in HubSpot. This can also be a good solution for companies with strict data security policies who do not want lead form data stored in ion for any period of time.

Check out the table below for a more detailed explanation of this method.

HubSpot: Get data via HubSpot REST API

You can leverage Ion’s Get Lead integration with the HubSpot REST API to optimize your Ion experiences. This integration enables you to retrieve data from HubSpot based on a respondent’s email address. You can leverage Get Lead to pre-populate (or shorten) Ion forms, auto-segment respondents and for progressive profiling.

This document provides step-by-step instructions to set up a REST API integration with HubSpot to get lead data. We’ll use the integration to pre-populate an Ion form in this document, but, as noted, there are a few different ways you can use Get Lead to enhance your ion experiences.

Before we begin

There are few items you’ll need to have ready in Ion prior to setting up the integration, listed below:

Check out the “Before you begin” support post for guidance in creating these items.

• Create data collection fields that will store HubSpot data
• Create Ion form(s)
• Set-up testing creative

Let’s Get Started!

1.  Add HubSpot account credentials to Ion

1. Click the Integrations tab in your Ion console’s side nav
2. Click “Set up account credentials” toward the top of the screen
3. Under “HubSpot”, click “New HubSpot credential”
4. Add a friendly label for your account
5. Save
6. You will be redirected to HubSpot to authenticate your credentials
7. After signing into HubSpot, click the Grant access button to allow the Ion platform to access your HubSpot account
8. After granting access, you will be returned to your Ion console.

2. Create field mapping

Taking the steps below will enable you to extend an email address value to HubSpot and map the data points returned to their corresponding ion data collection fields. To get started, add your new field mapping:

1. Navigate back to the Integrations screen
2. Click the green “New field mapping” button
3. Label the field mapping and optionally add a description
4. From the Integration type menu, select “HubSpot”
5. Save

3. Add Email Address as the Outbound field

The email address value will be used as the key to retrieve data from HubSpot.

1. Click the green “New outbound field” button
2. Select the Data field from the Source drop-down
3. Select Contact Info > Email Address
4. Make the field required for the integration to run
5. Select the corresponding HubSpot Email Address field
6. Save 

4. Create Inbound fields

Inbound fields will map the data HubSpot returns into their corresponding Ion data collection fields.

1. Click the green “New inbound field” button
2. From the Target dropdown menus, select the Ion data collection field you seek to populate with HubSpot data
   • To pre-populate Ion forms with HubSpot data, be sure to select the data collection field used on your form
3. From the Source dropdown, select the HubSpot field you want to pull data from
   • OR, select Javascript code if you want to transform the HubSpot data prior to storing it in ion data collection
   • Use responseBody.hubspot_field_name to access the HubSpot field via Javascript
4. Save
5. Repeat these steps for each HubSpot data field you seek to save into ion data collection

5. Create integration

1. Navigate back to the Integrations screen
2. Click into the Integrations tab
3. Click the green “New integration” button
4. Enter label
5. Optionally add a description
6. Select the Field Mapping you’ve just created
7. Skip Maximum retries
8. Select Get Lead as the API method
9. Select the outbound Email Address field
10. Optionally add yourself to the debug distribution list for testing
    • This will deliver an email to the designated address when the integration runs that displays the request and response from HubSpot
    • Check Only send error emails if you want to receive the debug email only when there is an error

6. Add integration to ion pages

The Ion platform runs the integration based on the rules you create. For HubSpot Get Lead, the rule will typically run the integration at the page-level of the landing page. You can, however, run the integration on any actionable step in your Ion experience. The steps below walk through adding the rule at the page-level to populate an ion form with HubSpot data.

1. Navigate into the testing creative with a form that you set up prior to beginning the integration steps
2. Under the Page tab in creative studio, click on +RULES
3. Add the following rule:
   • Condition: No conditions required
   • Action: Run integration (select HubSpot Get Lead integration)
4. Save

7. Test integration

Please note, integrations do not run in Preview Mode, so you’ll want to open a URL for your testing creative. Either pass an email address into your Ion page on the query string or submit your initial form that collects the email address. If passing an email address into Ion on the query string, be sure that the parameter name you append to the URL matches the “data name” of the Ion data collection field selected as the outbound field in your Field Mapping.

Once the integration runs, the form you seek to pre-populate will display the data retrieved from HubSpot. If you’re on the debug email distribution list, you’ll receive an email that displays the request and response from HubSpot.

Nice work!

Once you’ve completed these steps, your integration is ready for use. You can add the rule to run the integration on all applicable creatives.

As noted, HubSpot Get Lead can be used to accomplish other objectives. Here are some examples that can be accomplished using this integration and ion’s Rules engine:

• Shorten or replace forms
• Auto-segment respondents
• Build progressive profiles
• Serve-up dynamic content based on HubSpot data

Feel free to reach out to our Support team for assistance in leveraging this integration.

HubSpot: Post data to HubSpot form

Data collected through your Ion experiences can be submitted to a HubSpot form by leveraging ion’s ‘post to web form’ integration. This document provides step-by-step instructions to create an integration that posts data to a HubSpot form. Be sure to check out the Advanced Options section of this article to learn about posting to multiple HubSpot forms, including valuable dialogue data and the HubSpot tracking cookie.

Click here if you want to check out the advanced Integration options!

 

Before We Begin

There are few items you’ll need to roundup from HubSpot prior to setting up the integration. The HubSpot support document linked here provides further information around the items noted below:

• HubSpot form field names
• HubSpot form GUID
• HubSpot endpoint URL

There are a few steps to take in the Ion platform before setting up the integration. The Before You Begin support document linked here provides more information on the items listed below:  

• Create data collection fields
• Create Ion form(s)
• Set-up testing creative

Let’s get started!

1. Create field mapping

Taking the steps below will map your Ion data collection fields to their corresponding HubSpot field names. To get started, add your new field mapping:

1. Click the Integrations tab within your Ion console’s side nav
2. Click green “New field mapping” button
3. Label the field mapping “HubSpot” and optionally add a description
4. From the Integration type menu, select “Post to Web Form”
5. Save

2. Add Outbound fields to field mapping

Outbound fields define the data you extend from Ion to your HubSpot web form.

1. Click the green “New outbound field” button to add a new field to your field mapping
2. When adding a new field, you will either select from the Data Collection drop-down menus, Core Field drop-down menu, implement a mashup template or add a field via JavaScript
   • To add a form field, use the Data Collection drop-down menus to select the data field category then the data collection field
   • OR, to add an Ion Core field, select from the Core Field drop-down menu
   • OR, to export multiple ion fields to one external field, pick Mashup and plug inside {% raw %} {{DataName}} {% endraw %} {% raw %} {{DataName2}} {% endraw %}, etc. into the editor
   • OR, to reformat a value prior to export, use the JavaScript field to add logic around the value collected in ion. To access data collection fields via Javascript, use respondent.dataname.

• Optionally make your field required to run the integration
• Optionally add a default value
• Enter the external field name
• Save
• Repeat these steps for each field that should be included in the Field Mapping
• Skip inbound fields

Some of your lead data will be automatically sent by Ion and saved as properties of the new contact created in Hubspot. This means it is not necessary to add extra fields to either instances to collect the following data:

– Date of Conversion
– Traffic Origin
– Number of visits from this contact to this Form
– First Conversion Form from this contact
– User’s IP Address (City, Country and Region)

Other data can also be sent and saved as properties. This will depend on what information Hubspot is able to identify on its pages. For the complete list, see the properties tied to the contacts that converted in your Ion integrated Forms. 

3. Create integration

1. Navigate back to the Integrations screen
2. Click into the Integrations tab
3. Click the green “New integration” button
4. Enter “Post to HubSpot” as the label
5. Optionally add a description
6. Select the Field Mapping you’ve just created
7. Paste your Form URL into the editor
   • https://forms.hubspot.com/uploads/form/v2/:portal_id/:form_guid
      
8. This is the HubSpot form URL which needs to be configured like so:
   • https://forms.hubspot.com/uploads/form/v2/999999/abcd1234abcd1234abcd1234abcd1234
      
9. Set maximum retries
   • If there is a service interruption with the external platform, ion will retry the post on the top of the hour for as many retries as you indicate here.
10. Check “Empty Fields” to exclude external fields that do not have values from the POST data
11. Select POST as the method
12. Optionally add Debug email address
    • Email addresses specified here will receive an email each time the integration runs that displays the data posted and the response received. This is typically only used for testing and troubleshooting.
13. Skip Save Response As, Authentication and custom headers
14. Save

4. Add integration to ion pages

The Ion platform runs the integration based on the rules you create. Rules can be added to any actionable item in your Ion creative. Integration rules are typically run at the form-level, upon form submission, or on an assessment step. Follow the steps below to add the integration to your Ion pages.

1. Navigate into the creative
2. Click on the form, button or link you seek to make the trigger to run your integration
3. In Creative Studio, click on +rules
4. Select the condition that needs to be met to run the integration
   1. “No conditions required” is typically used
5. Select “Run integration in background” as the action
6. Save

5. Test integration

Use the creative you set up prior to beginning the integration steps to test your integration. Please note, integrations do not run in Preview Mode so you’ll want to open a URL for testing. The integration will run once you submit the Ion form, or complete the action that runs the integration rule. If you’re on the debug email distribution list, you’ll receive an email that displays the data posted and response from the external server. You’ll also want to check that the data you submitted was received by the external platform.

Advanced Options

Post to multiple HubSpot forms

If you seek to post Ion leads to campaign-specific HubSpot forms, there are two routes you can select from to accomplish this objective:

1. Make the HubSpot endpoint URL dynamic, supported by a form rule that saves the Form GUID

In the Ion integration, replace the GUID on the endpoint with a dynamic placeholder, like so: https://forms.hubspot.com/uploads/form/v2/:portal_id/{% raw %}{{HubFormGUID}} {% endraw %}

Above the form-level rule action that runs the integration, save the GUID value:

Condition: No conditions required

Action: Save data – HubFormGUID = paste GUID value here

2. Create new integration for each HubSpot form

Instead of leveraging a dynamic endpoint, you can create a new integration for each HubSpot form you seek to post to. Given that the HubSpot field names are consistent, you can leverage the same field mapping for each integration, and just paste a new endpoint into +Integration.

Include Dialogue Data in post

Data collected outside of your Ion forms can be included in the post to HubSpot. Results generated through rule calculations, Ion Core Fields and query string parameters are examples of supplemental data points that can be included in the post to HubSpot. As long as these data points are available when the integration runs, they can be included to enhance the contact record! To accomplish this, create fields to receive the desired data points on your HubSpot form(s) and include them in the Ion field mapping. 

Add HubSpot lead activity tracking

In order to associate analytics metrics with a contact record in HubSpot, you’ll need to add your HubSpot tracking code to your Ion form pages and include a special field called HS Context in the post. HS Context is a JSON formatted block that contains contextual information for the form submission, including the HubSpot tracking cookie token value, the IP Address of the lead converting, the URL the form is submitted on, and the name of the page the form is submitted on.

1. Add your HubSpot tracking code to ion’s script library

• Navigate to the script library (Libraries > Scripts)
• Click the green “New script category” button and create a category named HubSpot (or navigate into existing script category)
• Click the green “New script” button, label your new script Visitor Tracking, paste in the HubSpot tracking code, and save

2. Add the server scriptlet that saves the HS Context value

• Navigate to the server scriptlet library (Libraries > Server Scriptlets)
• Click the green “New scriptlet category” button and create a category named HubSpot
• Click the green “New scriptlet” button, label your new scriptlet Save HS Context, and paste the following into the scriptlet editor:

var hutk = actionReadCookie(“hubspotutk”);actionSaveData(“hutk”,hutk); var ip = respondent.ipaddress;var tsurl = respondent.deeplinkurl;var pname = respondent.pagelabel; var hscontext = {“hutk”:hutk,”ipAddress”:ip,”pageUrl”:tsurl, “pageName”:pname}; var hub = JSON.stringify(hscontext);  actionSaveData(“hscontext”,hub);

3. Update your integration’s field mapping to include the HS Context value as an outbound field

• Navigate to the integration field mapping (Integrations > Field Mappings > [Your Field Mapping])
• Click green “New outbound field” and create a new outbound field that uses {% raw %} {{hscontext}} {% endraw %} in the mashup template field option and External Field hs_context
• Save

4. Add your HubSpot Visitor Tracking script to your testing creative

• Navigate to the Creative Management screen for your creative
• Click “Edit creative properties” button on the right side of the Creative Management screen
• From the Creative-wide </body> library script editor, select HubSpot as the category and Visitor Tracking as the script from the dropdown menus
• Save

5. Add the HubSpot Save HS Context scriptlet to your testing creative

• Navigate to the form page in the creative studio
• Find your form-level rules and add an action to your integration rule that runs the Save HS Context server scriptlet before the HubSpot integration
  • Conditions: No conditions required
  • Action: Run server scriptlet – HubSpot/Save HS Context
  • Action: Run integration in background – Post to HubSpot

Note: You can run the integration from the scriptlet instead, if you seek to reduce the amount of rule actions. When using this method, select “Run server scriptlet” as your rule action and remove the “Run integration in background” action. Modifications to the scriptlet are required.

Nice work!

Once you’ve completed these steps, your integration is ready for use. You can add the rule to run the integration on all applicable creatives. If you run into any questions, please reach out to our Support team.

HubSpot: Embed HubSpot forms in Ion

If you’d like to embed HubSpot forms into your ion experiences, check out this post to easily repurpose your HubSpot embed code into a reusable ion widget. Taking these steps will enable you to redirect respondents to an ion page after form submission and to add ion rule logic to your HubSpot forms.

Before we begin

Before setting up a HubSpot form widget in ion, you will want to understand where to find your HubSpot portal ID and the form ID of the HubSpot form(s) you want to add to your ion pages.

Your HubSpot portal ID is a numeric value that is always present in the URL of every page within your HubSpot account. For example, when reviewing contacts in your HubSpot account, your URL should look something like the below. In this example, we’ve made the portal ID bold to make it easy to identify the portal ID.

https://app.hubspot.com/contacts/123456/contacts

You’ll also need to understand where to find your form IDs. The form ID is a longer alpha-numeric string that you will see in the URL when editing your HubSpot form or viewing form performance in HubSpot. Please find examples below of URLs you will see in your address bar when editing a HubSpot form or viewing performance with the form ID bold. 

Edit Form:

https://app.hubspot.com/forms/123456/editor/a1bbbcd2-345b-1234-1234-1a23b456c789/edit/form

Form Performance:

https://app.hubspot.com/forms/123456/a1bbbcd2-345b-1234-1234-1a23b456c789/performance

Let’s get started

Now that you know where to find your HubSpot portal ID and form ID values, we can start working on the form widget in ion. You can put your portal ID and form ID values to the side for now until it’s time to add your HubSpot form widget to a page.

Add widget code to your ion library

The first step in ion is to add the below code to your ion Widget Library.

In ion, navigate to Libraries > Widgets and click the New widget button to add a new widget. We recommend labeling the widget something like Embed Form and storing it in a category called HubSpot. 

Next, paste the widget code below into the editor.

<script src=”https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js”></script>

<!–[if lte IE 8]>

<script charset=”utf-8″ type=”text/javascript” src=”//js.hsforms.net/forms/v2-legacy.js”></script>

<![endif]–>

<script charset=”utf-8″ type=”text/javascript” src=”//js.hsforms.net/forms/v2.js”></script>

<script>

hbspt.forms.create({

portalId: ‘##portalId’,

formId: ‘##formId’,

  onFormSubmitted: function($form) {

top.location.href = ‘##OnSubmittedUrl’

},

});

</script>

This code includes variables that you will be able to populate with your portal ID and form ID when the time comes to add it to your page. It also includes a variable that will allow you to specify what page to go to when the form is submitted.

Before saving, go ahead and set the Portal ID and Form ID as required text and Next Page as a required action, like the example below:

 Add the widget to your ion experience

Navigate to the page where you’d like to embed the HubSpot form. Drag the Widget icon from the Basics palette onto your page and select your new HubSpot > Embed Form widget. Next, under Variables in Creative studio, enter the portal ID and form ID, in the Source text option, from your HubSpot account and select the ion page you seek to redirect to.

Voila! Your HubSpot form is now embedded in your ion experience! You can even add ion rule logic to your HubSpot form.