# HubSpot

Update or create the HubSpot contact behind each submission, matched by email.

## 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. **Open Form settings → Integrations**

   Choose HubSpot in the CRM group.

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. **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. **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](#requests).

> **Make the email question required**
>
> A submission without an email answer has no contact to update, so its delivery fails and is not retried. Mark the question you mapped to Email as required.

## 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

| Form field | Compatible HubSpot properties |
| - | - |
| Any field | Single-line text, Multi-line text |
| Number, Rating, Scale | Number, plus text |
| Date | Date picker, Date and time picker, plus text |
| Phone | Phone number, plus text |
| Radio, Dropdown, Checkboxes, Picture choice | Dropdown select, Radio select, Multiple checkboxes, plus text |
| Toggle switch | Single checkbox, plus text |
| Repeating group (whole group) | Text only |

- 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** under 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. On Pro and Business you can tick several contacts and add them at once, one request each: see [Bulk send](https://docs.formstep.io/requests/bulk-send/). You can still change anything before you send. When the recipient completes the [request](https://docs.formstep.io/requests/overview/), 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.

> **Only in the dashboard**
>
> The API and MCP don’t read HubSpot. An automation that creates requests looks the contact up itself (n8n and Zapier both have a HubSpot step for it) and passes the values in `prefill`. Prefill and lock the field mapped to Email with the contact’s email, and the answers update that contact by email. See [Prefill](https://docs.formstep.io/requests/creating-requests/#prefill).

## 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](https://docs.formstep.io/integrations/health-monitoring/#failed-deliveries) to send it again.

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

## FAQ

**What access does Formstep need?**

Read and write contacts, and read the contact property definitions. Formstep uses OAuth, so there are no API keys to manage, and it doesn’t ask for access to companies, deals, or other objects.

**Can other workspace members see my HubSpot connection?**

Yes. HubSpot connections are workspace-scoped. Any member can use any connected account when setting up an integration.

**Can I connect multiple HubSpot accounts?**

Yes. Connect another account during a new integration setup. Each form picks which account to use.

**Does an edit create a second contact?**

No. The edit updates the contact with the email in the submission. If the respondent changes the email answer itself, the new email is a different contact, so that contact is updated or created instead.

**How do I remove the integration?**

Go to Form settings → Integrations → HubSpot and delete the integration. To also revoke Formstep’s access, uninstall the Formstep app in HubSpot under Settings → Integrations → Connected apps.

## Next steps

[Creating requests](https://docs.formstep.io/requests/creating-requests/) — Prefill and lock fields for one recipient

[Integration health](https://docs.formstep.io/integrations/health-monitoring/) — Event logs, retries, and failure emails

[Airtable](https://docs.formstep.io/integrations/airtable/) — Create records in an Airtable base