HubSpot

What you get

• One HubSpot contact per email address: an existing contact is updated, a new email creates a contact
• Field-level mapping to contact properties, with type compatibility checks
• A respondent’s edit updates the same contact again
• Empty answers never clear a property, and properties you don’t map stay as they are
• A legal basis for new contacts, for accounts that require one
• A test send that only touches a dedicated test contact
• Find a contact in the New request sheet, prefill the request from it, and write the answers back to that contact

Connect HubSpot

1. 1

   Open Form settings → Integrations

   Choose HubSpot in the CRM group.

2. 2

   Connect a HubSpot account

   Pick an existing connected HubSpot account, or connect a new one. You'll be redirected to HubSpot to choose the account and approve access. Formstep then loads the account's contact properties and shows how many are ready to map.

3. 3

   Map form fields → contact properties

   Match each form field to a contact property. Only compatible properties are shown. One form field must be mapped to Email, because that is how the contact is found. The arrow on each row sets which way values go: → answers update HubSpot, ← a contact you pick prefills the field, ↔ both. If the account asks for a legal basis, pick one here too.

4. 4

   Finalize

   Use "Send test" to write sample values to the test contact formstep-test@example.com. New submissions start updating contacts once you save.

How a submission finds its contact

The answer to the form field you mapped to Email decides which contact a submission belongs to. On each completed submission, Formstep:

1. Updates the HubSpot contact with that email, writing only the properties you mapped.
2. Creates the contact when no contact has that email. A new contact gets the mapped answers, the email, and the legal basis.

When a respondent edits their submission, the same contact is updated again with the new answers. An answer left empty is skipped, so it never clears a value already in HubSpot, and properties you didn’t map are never touched.

A request you prefilled from a contact in the New request sheet is the exception: its answers update that contact, whatever email is typed. See Requests and prefill.

Legal basis for new contacts

HubSpot accounts with data privacy settings turned on, which is the default for accounts in the EU, refuse to create a contact without a legal basis for processing its data. When your account has that setting, the Configure step shows Legal basis for new contacts with your account’s own options, and you must pick one before you can continue.

Formstep writes the legal basis only when it creates a contact. An existing contact keeps the legal basis it already has, because that value records the consent your team collected. The legal basis is never offered as a mapping destination.

Property types

• A choice answer goes to the HubSpot option whose internal value or label matches the Formstep option’s key or label, ignoring case. An answer with no matching option is left out rather than failing the whole write.

• Several selected options go to a Multiple checkboxes property together.

• Metadata can be mapped as well, for example Submitted at to a date property or PDF Link to a text property.

Read-only, calculated, hidden, and archived properties can’t be written, so they are not offered. The property list refreshes each time you open the integration; if it fails to load, press Try again.

Test event

The Finalize step and the integration detail panel both have a Send test button. It writes to the contact formstep-test@example.com, creating it if it doesn’t exist, and never changes any other contact. Text properties get [Question title] strings, numbers get 0, dates get today’s date, single checkboxes get No, and dropdowns use the property’s first HubSpot option. Delete the test contact in HubSpot when you’re done.

Requests and prefill

With a HubSpot integration on the form, the New request sheet shows Find in HubSpot above the recipient. Search by name, email, phone or company and pick a contact: its email and name become the recipient, and every form field whose row prefills (← or ↔) takes the contact’s value. You can still change anything before you send. When the recipient completes the request, the answers update that same contact by its id, even if they typed a different email, and the contact’s email is never changed.

• Values are read once, when you pick the contact. A change in HubSpot after that does not reach the request.

• A field that cannot be prefilled keeps a plain → arrow: a file, a signature, a payment, a list of options, a matrix, a repeating group, metadata or a calculated field. A hidden field takes its value as context.

• A choice field takes the option whose key or label matches the HubSpot option, ignoring case. A value that fits no option is left out.

• Try it yourself fills the same values but never updates HubSpot: a test request does not reach integrations.

• If the contact is deleted before the recipient submits, the answers go to the contact with the submitted email instead.

What it doesn’t do

• Abandoned submissions are not sent to HubSpot. Only completed submissions and edits update contacts.
• Existing submissions are not exported when you connect. Contacts are updated from the next submission on.
• It writes contacts only, not companies, deals, or tickets.

Property changes in HubSpot

Formstep reads the mapped properties’ current definitions on every delivery. If you delete a mapped property in HubSpot, it is left out of the write and the rest of the contact still updates. If a property’s type or options change, answers are converted to the new definition; when the new type no longer fits the form field, the mapping shows a warning so you can map that field again.

Troubleshooting

• Authorization expired — HubSpot access tokens last 30 minutes and are refreshed automatically. If the refresh fails, for example because the app was uninstalled in HubSpot, the connection is marked expired and its integrations stop. Press Reconnect.

• A value is rejected — HubSpot can refuse a value, for example one that breaks a validation rule set on the property. The failed entry under Recent events shows HubSpot’s own message. Fix the form field or the property, then see failed deliveries to send it again.

• Couldn’t load contact properties — press Try again. If it keeps failing, reconnect the account.

FAQ

Next steps