HubSpot Integration with HT Contact Form

Key Features

• Automatic Contact Creation: Create HubSpot contacts from form submissions
• Contact Deduplication: Existing contacts are updated, not duplicated
• Property Mapping: Map form fields to any HubSpot contact property
• Custom Properties: Support for your custom contact properties
• List Assignment: Add contacts to HubSpot static lists
• Rate Limit Handling: Automatic handling of HubSpot API limits

Prerequisites

Before using the HubSpot integration, make sure you have a HubSpot Account (Free CRM or paid plan), a Private App Access Token created in HubSpot settings, and the required scopes enabled for contacts and lists.

Creating a Private App

1. Log in to your HubSpot account
2. Go to Settings (gear icon)
3. Navigate to Integrations → Private Apps
4. Click Create a private app
5. Enter app details: Name: HT Contact Form, Description: Contact form submissions
6. Go to the Scopes tab
7. Select the required scopes:
   • crm.objects.contacts.read – Read contacts
   • crm.objects.contacts.write – Create/update contacts
   • crm.lists.read – Read lists
   • crm.lists.write – Add contacts to lists
8. Click Create app
9. Copy the Access Token

Important: Store the token securely and don’t share it publicly. You’ll need it to configure the integration.

Step 1: Configure Global Settings

First, you need to configure the HubSpot Private App Access Token in the global settings.

1. Go to HT Contact Form → Settings → Integrations
2. Find HubSpot and click Configure
3. Enter your Private App Access Token
4. Click Verify and Save to test the connection

Step 2: Add HubSpot Integration to Your Form

Once the global settings are configured, you can add the HubSpot integration to any form.

1. Edit your form
2. Go to the Integrations tab
3. Click Add New → HubSpot
4. Map form fields to contact properties
5. Optionally select a List
6. Click Save Integration

Integration Settings Overview

Common Contact Properties

The integration displays the most commonly used HubSpot contact properties for mapping:

All editable contact properties from your HubSpot account are available for mapping. Custom properties appear after the common properties in the dropdown.

List Assignment

Optionally add contacts to a HubSpot static list after creation:

1. Select a list from the dropdown
2. Only Manual and Snapshot lists are shown (not dynamic lists)
3. Contact is added to the list after creation/update

List Types

Note: Dynamic (Active) lists cannot be used because HubSpot manages their membership automatically based on filter rules.

Property Types

HubSpot properties have various types. The integration sends values as strings, and HubSpot handles type conversion:

Enumeration Properties

For dropdown/select properties in HubSpot, use the internal value, not the display label:

HubSpot Property: Lead Status
Options:
  - Label: "New Lead" → Value: "new"
  - Label: "In Progress" → Value: "in_progress"

Use: hs_lead_status: new (not "New Lead")

Smart Tags Reference

Use {input.field_name} to pull values from form fields.

Complete Configuration Example: Lead Capture Form

Here’s an example of setting up HubSpot integration to capture leads from a contact page.

Form Fields: First Name, Last Name, Email, Phone, Company, Message

Integration Configuration

Property Mapping:
  email: {input.email}
  firstname: {input.first_name}
  lastname: {input.last_name}
  phone: {input.phone}
  company: {input.company}
  message: {input.message}
List: Website Leads

Result: New contact created (or existing updated) and added to “Website Leads” list.

Common Use Cases

• Lead Capture and Nurturing: Capture leads through contact forms and add them directly to HubSpot for automated nurturing sequences and sales follow-up.
• Newsletter Signups with CRM Tracking: Subscribe users to your newsletter and track them as contacts in HubSpot for personalized marketing campaigns.
• Event Registration Management: Collect event registrations and create HubSpot contacts with event-specific properties for targeted follow-up communications.
• Customer Support Intake: Create or update contact records when customers submit support requests, maintaining a complete interaction history.
• Lead Source Segmentation: Capture leads from different website pages and tag them with source properties for marketing attribution analysis.
• Qualification and Scoring Setup: Collect qualification information via forms that populates HubSpot properties used in lead scoring and routing.

Contact Deduplication

HubSpot uses email as the primary identifier for deduplication:

• Email exists: Contact is updated with new property values
• Email is new: New contact is created
• No duplicate contacts: Same email always updates existing record

This prevents duplicates from form resubmissions or returning visitors.

Troubleshooting

Contacts Not Appearing

Problem: Form submissions don’t create contacts.

Solutions:

• Verify access token is valid (not expired)
• Check that required scopes are enabled
• Search for contact by email in HubSpot
• Check for errors in form submission logs
• Ensure email field is mapped (required)

Properties Not Updating

Problem: Contact exists but properties don’t change.

Solutions:

• Verify property exists in HubSpot
• Check property is editable (not read-only)
• Confirm smart tag syntax matches form field
• For enumerations, use internal value, not label

List Assignment Failing

Problem: Contact created but not added to list.

Solutions:

• Confirm list is Manual or Snapshot type
• Verify list still exists in HubSpot
• Check list write permissions in Private App scopes
• Test with a different list

Invalid Token Errors

Problem: “Invalid access token” after working previously.

Solutions:

• Check if Private App was deleted in HubSpot
• Verify token hasn’t been regenerated
• Create a new Private App if needed
• Re-enter the new token in settings

Frequently Asked Questions

Q: Do I need a paid HubSpot account?
A: No, HubSpot’s free CRM includes API access. Paid plans add features but aren’t required for this integration.

Q: What happens if someone submits the form twice?
A: HubSpot uses email for deduplication. The existing contact is updated with new values; no duplicate is created.

Q: Can I add contacts to multiple lists at once?
A: Add multiple HubSpot integrations to the same form, each targeting a different list.

Q: Can I trigger HubSpot workflows from form submissions?
A: Yes! Create workflows that trigger on “Contact joins list” or “Contact property change” events.

Q: How do I map to custom properties?
A: Custom properties appear in the mapping dropdown after the common properties. Use the property’s internal name.

Q: Why don’t I see dynamic lists in the dropdown?
A: Dynamic (Active) lists are rule-based and don’t allow manual additions. Use Manual or Snapshot lists instead.

Q: Can I update contacts without adding to a list?
A: Yes, the list selection is optional. Leave it empty to just create/update contacts.

Best Practices

Property Mapping

• Always map email – Required for contact identification and deduplication
• Include names – firstname, lastname for personalization
• Map company data – company, jobtitle for B2B context
• Use appropriate properties – Match form data to relevant HubSpot properties

List Management

• Create specific lists – One list per form or campaign
• Use clear names – “Website Leads – Contact Page” not just “Leads”
• Avoid dynamic lists – Use static lists for form submissions
• Set up list-based automation – Trigger workflows when contacts join lists

Data Quality

• Validate email format – Use email field validation in forms
• Standardize data – Use dropdowns for enumeration properties
• Map consistently – Use same mappings across similar forms
• Test thoroughly – Submit test entries and verify in HubSpot

HubSpot Workflows

• Trigger on list add – Create workflows that trigger when contacts join lists
• Use property changes – Trigger workflows when mapped properties change
• Set up lead scoring – Use mapped properties in scoring criteria
• Notify sales – Alert team when high-value leads come through

That’s it! Thank you for choosing HT Contact Form to enhance your CRM workflow. If you need additional assistance, feel free to contact our support team. Our dedicated support team would be more than happy to assist you.