Connecting a form on your WordPress website to HubSpot is quick to start. A few clicks link the accounts and a list of fields appears for you to match.
The trouble comes later. Sales opens a contact record and finds the phone number in the wrong place. A drop-down answer is blank. The company name has landed in a field nobody uses. The connection “works”, but the data is not usable.
Most of these problems come from skipping a short planning step: deciding, before you connect anything, which form field goes where and what it means. This article explains how to do that and gives you a mapping sheet.
The official Gravity Forms HubSpot Add-On is one common way to connect them; other connectors work differently. This article draws on that add-on’s documentation, but the planning questions are the same whichever connector you use.
What the connection does
In the Gravity Forms HubSpot Add-On, a feed links one form to HubSpot. According to the Gravity Forms documentation:
- Each feed maps form fields to HubSpot contact properties. The email field is required.
- The first submission with a given email address creates a contact. Later submissions with the same address update that contact.
- You can set a lead status and a lifecycle stage for the contact.
- You can map additional contact properties, including custom ones you create in HubSpot.
- You can apply conditional logic to decide which submissions are sent.
The documented feed settings concern contacts. If your process relies on company records, deals or other objects, check what your connector supports, and how those records will be created and linked, before launch. Do not assume the form connection does it for you.
Why plan first
Two things make mapping easy to get wrong.
The same word means different things. “Name”, “company” and “phone” can describe a person, an organisation or a mobile versus a landline. HubSpot keeps separate properties for contacts and companies. Mixing them leaves records that look complete but cannot be searched or reported on properly.
Some details cannot be changed later. In HubSpot, you can rename a property’s label but you cannot change its internal name or object type afterwards. Choices in drop-down properties need to match what your form sends. It is easier to decide first than to repair.
Step 1: list what your team actually needs
Start from the follow-up process, not the form. Ask the people who will use the data:
- What do you need to know before contacting this person?
- What do you filter or segment by?
- What triggers an email, task or reminder?
- Which details are required, and which are optional?
Then remove anything that nobody uses. Every extra field adds clutter to the form and to HubSpot.
Step 2: separate people from organisations
Write down which details describe the person and which describe their business.
- Person details: first name, last name, email, phone, job title.
- Organisation details: company name, website, industry, company size.
HubSpot can associate contacts with companies, and an account setting can link them automatically by email domain. Check what is configured in your account. Because personal email domains such as gmail.com do not identify a company, don’t rely on domain matching alone.
A common, sensible compromise: collect the company name as a text field on the form, map it to the contact’s company-name property and let your HubSpot administrator decide whether and how company records are created. Whichever approach you choose, write it down.
Step 3: check the types and choices
For each field, note the type on both sides.
| Type on the form | Possible match in HubSpot | Watch for |
|---|---|---|
| Single line text | Single-line text property | Length limits and formatting |
| Email property | Required for contact creation | |
| Phone | Phone number property | Format and country codes |
| Drop down, radio buttons or checkboxes | Dropdown select, radio select or checkbox property | Values must match exactly |
| Consent | Checkbox or a consent-related property | Wording and what it records |
| Date | Date property | Date format |
| Free text message | Multi-line text property | Where staff will read it |
The Gravity Forms documentation points out several details about choices:
- For choice fields, each value must exactly match the value of the corresponding HubSpot property option.
- Radio buttons and drop-downs may need “Show Values” turned on in the form field settings, so the form sends a value rather than a label.
- Quiz, poll and survey fields cannot be mapped.
If your drop-down says “Residential” and HubSpot expects “residential” or “Residential property”, the value may not be accepted or may come through blank. Compare the exact spelling.
Step 4: create custom properties first
If you need a property HubSpot does not have, create it in HubSpot before building the feed. Then note that Gravity Forms caches the list of HubSpot properties for around an hour, so a brand-new property may not appear straight away. The add-on has a “Clear Custom Field Cache” button in the HubSpot settings for this.
Agree property names with whoever manages HubSpot, so that a “Preferred contact method” field does not become three similar properties.
The mapping sheet
Copy this table and complete it before configuration. The examples use made-up details and a made-up form, not any real client’s.
Form: “Request a consultation”. Team who follows up: Business enquiries team (example).
| Form field (label) | Field type | Meaning | HubSpot object | HubSpot property (label) | Required? | Allowed values / notes | Tested |
|---|---|---|---|---|---|---|---|
| First name | Text | Person’s given name | Contact | First name | Yes | ||
| Last name | Text | Person’s family name | Contact | Last name | Yes | ||
| Person’s work email | Contact | Yes | Required by the feed; used to match existing contacts | ||||
| Phone | Phone | Best number to call | Contact | Phone number | No | Confirm format | |
| Company | Text | The person’s organisation | Contact | Company name | No | Company records handled separately (decision needed) | |
| Role | Text | Job title | Contact | Job title | No | ||
| I’m enquiring about | Drop down | Service of interest | Contact | Service interest (custom) | Yes | “Advice”, “Training”, “Support”. Must match HubSpot options exactly | |
| Message | Paragraph | Free-text question | Contact | Enquiry message (custom, multi-line) | No | Staff read this first | |
| Consent to be contacted | Consent | Agreement to follow-up | Contact | Marketing consent (custom checkbox) | Yes | Wording agreed with adviser | |
| (Hidden) Source form | Hidden | Which form sent this | Contact | Lead source detail (custom) | Auto | Fixed text: “Website – consultation form” |
A few habits make the sheet more useful:
- Include a “meaning” column. It forces a decision when two fields sound alike.
- Mark every fixed value, such as the hidden source field.
- Add a “decision needed” note rather than guessing.
- Share the sheet with the person who manages HubSpot, before building.
Step 5: decide the rules for existing contacts
Think about what should happen when the same person submits twice, or when a contact already exists.
- With the Gravity Forms add-on, a new submission with a known email updates the existing contact. Decide whether overwriting existing values is acceptable. For example, an old phone number replaced by a new one is usually fine, but an old note overwritten by a blank one is not.
- The add-on includes a setting about creating a new contact for each unique email address, and an option to exclude HubSpot’s tracking cookie from a feed. Both affect which contact record a submission attaches to. The Gravity Forms documentation notes that with the tracking cookie, submissions made in the same browser session can update the same contact. This matters when you test, because testing repeatedly from one browser may update one record rather than create new ones.
- Decide who owns data quality, and who fixes mismatches.
Step 6: test with dummy records
Never test with real customers. Create a few made-up contacts with obvious names and addresses you control. Then:
- Submit the form with every field filled in. Check each property in HubSpot against the mapping sheet.
- Submit with optional fields blank. Check nothing is overwritten.
- Submit each drop-down choice at least once. Check the values arrive.
- Submit again with the same email. Check the record updates, not duplicates.
- Test any conditional logic by submitting both paths.
- Look at the website’s own stored entry too. It should match what was sent.
- Delete or label the test records afterwards.
Our guide to testing a website form properly covers the rest of the chain, including notifications and analytics.
A successful test of one part does not prove the rest. The entry can be saved while the HubSpot feed fails, or the feed can succeed while the email notification does not arrive.
Keep records after launch
Keep the mapping sheet somewhere safe. When someone later adds a field to the form, edits a HubSpot property or changes a drop-down option, they can see what depends on it. Changes made in one system without updating the other are a common cause of “missing” data.
HubSpot also creates a form in your account for each feed. The Gravity Forms documentation advises against editing or deleting that form, so don’t.
Working with an agency or CRM specialist
Form mapping often sits between teams: a website developer, a marketing agency, a CRM administrator. The clearest projects divide responsibility explicitly. On our Radically project, we worked on HubSpot forms and gated guides, set up with the HubSpot team at their marketing agency.
A division that works well:
- The website developer builds the form, applies the mapping and tests the website side.
- The CRM or marketing owner manages properties, lifecycle rules, workflows and reporting.
- The business owner confirms what the data must support and signs off the tests.
Whoever does what, write it down.
A sensible next step
Fill in the mapping sheet for your most important form before anyone touches the settings. Even a half-complete sheet shows where you need decisions.
If you want help connecting WordPress forms to a CRM, see our WordPress services or send us your draft sheet. We can check it against how the form is built.
