# HubSpot Update or create the HubSpot contact behind each submission, matched by email. Map fields to contact properties, and pick contacts as recipients of a request. ## What you get - One HubSpot contact per email address, updated or created - Each field mapped to a contact property of a matching type - Edits update the same contact again - A legal basis for new contacts, for accounts that need one - A test send that changes only a test contact For an overview, see [Formstep for HubSpot](https://formstep.io/integrations/hubspot/). ## Connect HubSpot 1. **Open Integrations** Click **Integrations** (plug icon) in the form's top bar, then pick HubSpot under CRM. 2. **HubSpot account** Pick a connected HubSpot account, or click **Connect HubSpot account**. Formstep then loads the account's contact properties. 3. **Contact properties** Match each form field to a contact property. Only compatible properties are listed. Map one form field to Email: Formstep finds the contact by it. If the account needs a legal basis, pick one here too. 4. **Turn it on** Click **Turn on HubSpot**, then **Send test** to write sample values to the test contact formstep-test\@example.com. ## How a submission finds its contact The answer mapped to **Email** picks the contact. 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, Formstep updates the same contact again. An empty answer never clears a value in HubSpot. Formstep never changes properties you did not map. > **Make the email question required** > > Without an email answer, the delivery fails and is not retried. Make the question you mapped to Email required. ## Legal basis for new contacts With data privacy settings on, HubSpot creates no contact without a legal basis. EU accounts have this setting by default. Then the Configure step shows **Legal basis for new contacts** with your account’s options. Pick one to continue. Formstep writes the legal basis only on a new contact. An existing contact keeps its legal basis, because it records the consent your team collected. You cannot map a form field to the legal basis. ## 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, and the rest of the write goes through. - 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 are not listed. The property list refreshes each time you open the integration. ## Test event **Send test** writes placeholder values to the contact `formstep-test@example.com`, and creates it if needed. It never changes any other contact. Delete the test contact in HubSpot when you are done. ## Find HubSpot contacts for a request The New request sheet can also add people from HubSpot. Click **Import**, then **Find in HubSpot**, and search by name or email. A contact fills in the person’s email and name. Fill in the rest of the [request](https://formstep.io/docs/requests/overview/) as usual. On Pro and Business, tick several contacts to send one request each: see [Bulk send](https://formstep.io/docs/requests/bulk-send/). - The form needs no HubSpot integration for this. A contact you pick never fills in form fields. - The workspace owner connects HubSpot once, under Integrations or from **Import** › **Connect HubSpot**. Then everyone in the workspace can search it. When the connection expires, the owner sees **Reconnect HubSpot** there. - Answers reach HubSpot only through the form’s HubSpot integration, like every other submission. - **Try it yourself** never updates HubSpot: a test request does not reach integrations. > **Only in the dashboard** > > An automation cannot search HubSpot through Formstep. It looks the contact up itself, for example with the HubSpot step in n8n or Zapier, and prefills the request with what it found. Prefill and lock the field mapped to Email with the contact’s email, and the answers update that contact. See [Prefill, locked fields and hidden fields](https://formstep.io/docs/requests/creating-requests/#three-buckets). ## What it doesn’t do - Unfinished drafts are not sent to HubSpot. Only finished 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 - Delete a mapped property: Formstep leaves it out, and the rest of the contact still updates. - Change a property’s type or options: answers are converted to the new definition. - Change a property to a type that no longer fits the form field: the mapping shows a warning. Map that field again. ## When something goes wrong - If the integration shows **Connection expired**, for example because the app was uninstalled in HubSpot, click **Reconnect**. - HubSpot can refuse a value, for example one that breaks a validation rule on the property. The failed event under **Recent events** shows HubSpot’s message. Fix the form field or the property, then send it again with [Retry all](https://formstep.io/docs/integrations/health-monitoring/#failed-deliveries). - If the contact properties do not load, click **Try again**. If it keeps failing, reconnect the account. ## FAQ **What access does Formstep need?** Access to read and write contacts and to read their property definitions. You sign in with HubSpot, so there are no keys to manage. It does not ask for access to companies, deals or other objects. **Can other workspace members see my HubSpot connection?** Yes. HubSpot accounts are connected to the workspace. Any member can use any connected account in an integration. **Can I connect multiple HubSpot accounts?** Yes. The workspace owner connects more accounts, from Integrations or during setup. Each form picks one account. **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, Formstep updates or creates the contact with the new email. **How do I remove the integration?** Open Integrations, pick HubSpot under **On this form**, and choose **Delete integration** in the ⋯ menu. To also revoke Formstep’s access, uninstall the Formstep app in HubSpot under Settings › Integrations › Connected apps. ## Next steps [Send a request](https://formstep.io/docs/requests/creating-requests/) — Prefill and lock fields for one recipient [Health and monitoring](https://formstep.io/docs/integrations/health-monitoring/) — Retries, pausing and reconnecting [Client intake template](https://formstep.io/templates/client-onboarding/) — A form to prefill from a contact, whose answers update it [Email capture to a CRM-prefilled form](https://formstep.io/workflows/zapier-hubspot-prefill-form/) — A Zap that looks the person up in HubSpot and sends them a prefilled form