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.

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

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.