HubSpot

The native HubSpot integration records every new accepted Fillo response as a HubSpot Form submission on the Contact timeline. Each form can also create or update an associated Company and create one associated Deal per response. Explicit mappings keep unselected answers out of HubSpot.

Connect HubSpot

1. Open Workspace connections and choose Connect HubSpot.
2. Approve access to the HubSpot account that should receive CRM records.
3. Open the Fillo form's Settings → Response destinations → HubSpot.
4. Choose the required email field used as the Contact identity.
5. Add as many Contact-property mappings as the form needs. The picker includes writable standard and custom properties from the connected HubSpot account.
6. Leave Set new Contacts as marketing off unless the form should create billable marketing contacts in HubSpot.
7. To sync Companies, choose a field containing a company domain, website, or work email, then map any Company properties.
8. To sync Deals, choose a required Deal-name field plus a live HubSpot pipeline and stage, then map any optional Deal properties.
9. Choose Enable HubSpot sync, then submit a production-shaped test response.

One workspace connection can serve several forms. Each form owns its mapping, so a sales lead form and a partner application can send different fields to the same account.

Contact mapping

The required email answer is the Contact identity for create or update. Add a row for every other answer that should be sent, then choose any compatible writable Contact property exposed by the connected account. This includes custom text, number, date, boolean, and choice properties as well as standard properties such as first name, last name, phone, company, job title, and website.

Fillo sends the canonical formatted value for text properties. Number and date properties receive their typed answer value. Choice answers are matched to the HubSpot option's label or internal value and sent using HubSpot's internal value. If the HubSpot options later stop matching the form, delivery fails visibly in Activity instead of writing an unintended option. Unmapped answers stay out of HubSpot.

Blank optional answers are omitted. They do not erase a value already stored on the Contact. The email identity is always required and can't also be reused as an optional property mapping.

Fillo manages one HubSpot form named Fillo — <form name> for each enabled Fillo form. New responses use HubSpot's authenticated Forms endpoint, so HubSpot records the submission in the normal Contact activity stream. Owner edits in the Fillo response grid update the CRM properties without creating a second respondent Form submission.

The managed form creates non-marketing Contacts by default. Turning on Set new Contacts as marketing changes only new Contacts created through that form and can affect the HubSpot account's billable marketing-contact count. It does not change an existing Contact's marketing status.

When the form runs in a browser, Fillo forwards the page URL and title. If HubSpot tracking is already installed and the browser has a hubspotutk cookie, Fillo forwards that existing cookie too. Fillo never creates the cookie or loads HubSpot tracking code. This gives HubSpot the context it can use for traffic attribution; attribution is necessarily more limited on hosted Fillo pages or sites without HubSpot tracking.

Company mapping

Company sync is optional. Fillo normalizes the selected field to a domain, looks for an existing HubSpot Company with that standard domain, and adopts it when found:

• A work email such as ada@example.com becomes example.com.
• A URL such as https://www.example.com/about becomes example.com.
• Blank answers and common personal-email domains such as Gmail or Outlook skip Company creation for that response. Contact and Deal delivery still continue.
• An invalid nonblank domain fails loudly in Activity instead of creating an ambiguous Company.

Optional Company mappings are Company name, Phone, City, State / region, Country, Industry, and Description. Blank mapped answers do not clear existing Company properties.

For retry-safe updates, Fillo installs one unique text property named fillo_company_domain when the first Company workflow is saved. The value is the same normalized domain written to HubSpot's standard domain property. It is managed by Fillo and is not populated from respondent input.

Deal mapping

Deal sync is optional. Choose a required form field for the Deal name and select a pipeline and stage from the connected HubSpot account. Optional mappings are Amount, Close date, and Description.

Fillo installs one unique text property named fillo_response_id in HubSpot when the first Deal workflow is saved. The property is the retry-safe identity for the Deal; it is not populated from respondent input.

Create and update behavior

The CRM workflow uses a stable identity for every object:

• The first response for an email creates the Contact when it doesn't exist.
• Another response with the same email updates that Contact rather than creating a duplicate.
• Every new response creates its own native Form submission activity, even when it updates an existing Contact.
• Companies are matched against the standard domain, then created or updated using Fillo's unique normalized-domain property.
• Every accepted Fillo response gets its own Deal, keyed by the response ID.
• Retrying or replaying a response updates the same Contact, Company, and Deal, then safely restores any missing associations.

This means two different people must not share the same email identity if they should remain separate HubSpot Contacts. Separate responses from the same email create separate Deals while continuing to update the same Contact and Company.

Permissions and data boundary

Fillo requests OAuth identity, Forms, Contact read/write, Contact schema read, Company read/write, Deal write, and Company/Deal schema read/write scopes. Forms access creates the managed form and sends native submissions. Contact read access resolves the Contact ID after a native submission only when Company or Deal associations need it. Contact schema access loads writable standard and custom property definitions for the mapping picker. Company read access is used only to find and adopt a Company with the exact normalized domain before Fillo writes to it. Company and Deal schema access verifies or creates the unique fillo_company_domain and fillo_response_id properties. Fillo does not request marketing email or custom timeline-event access.

Older connections keep their existing CRM-only Contact sync working. Reconnect HubSpot once to enable native Form submission activity, browser attribution, Contact lookup for associations, and the complete property picker.

The workspace's access and refresh tokens are encrypted at rest. A form's mapping stores field IDs and the destination HubSpot account ID, not OAuth credentials. If the workspace reconnects a different HubSpot account, the form changes to Review mapping and delivery stops until a manager confirms the mapping for the new account.

Code-defined forms

The schema can live in code, but OAuth and CRM mappings are authenticated workspace settings. Sync and publish the form, then configure HubSpot in the dashboard. Keep mapped field IDs stable. If an identity, Deal-name, or mapped field is removed or becomes unsupported, delivery fails loudly in Activity instead of silently dropping the value.

Delivery behavior and limits

HubSpot deliveries use Fillo's durable integration queue, automatic retries, daily failure alert, and failed-delivery replay. Provider API and account limits apply independently of the Fillo plan.

Stopping the destination leaves the managed HubSpot form and existing Contacts, Companies, and Deals unchanged. Disconnecting the workspace account stops every form that uses it; reconnect HubSpot, review each affected workflow, then replay failed deliveries from the form's Activity page.

Troubleshooting FAQ

Why can't I choose an email field?

The form needs an email field marked required. Change the field in the builder, publish the schema when applicable, then reopen HubSpot setup.

Why did an existing Contact change?

HubSpot identifies this destination by email. Any accepted response using the same email targets the same Contact, and each nonblank mapped answer can update its property.

Why didn't a blank answer clear HubSpot?

Fillo intentionally omits blank optional answers to protect existing CRM data. Clear the property in HubSpot or use a reviewed workflow through Zapier or a signed webhook when clearing is an explicit business rule.

Why wasn't a Company created?

The selected domain answer was blank or resolved to a common personal-email domain. This is intentional: Fillo still delivers the Contact and Deal without creating a Company such as gmail.com shared by unrelated respondents.

Why do I need to reconnect HubSpot?

Older connections are missing the Forms and Contact read permissions used for native timeline activity, attribution, and associated-record lookup. Reconnecting once grants the complete permission set. Existing CRM-only workflows remain active until then.

Why does the form say Review mapping?

The workspace now connects to a different HubSpot account than the one captured when this form was configured. Open Manage, verify the fields, and save before replaying failed deliveries.

Related

• Delivery health and replay: Repair the connection and replay only failed HubSpot deliveries.
• Zapier: Build a multi-step or custom-property CRM workflow.
• Webhooks: Transform responses in infrastructure you control.