Mapping form fields into a marketing contact record

This guide uses HubSpot forms, which collect visitor information and create or update CRM records. Form fields store answers in the CRM properties they are connected to.

Map each answer to its destination property, then check a submitted record. A matching field label is not enough: check the connected property, its object, value type and what happens on repeat submissions.

Make a field map

For every visible, hidden or defaulted field, note the form label, connected property, object, expected value and intended treatment of a blank answer. For a blank optional answer, test whether the property remains unchanged or is cleared; do not assume either result.

Example map: Email → email → contact object → Email property type; Product interest → Product interest contact property → contact object → Dropdown select. For Company name, connect the field to the default Company name property on the company object when that is where the answer belongs; otherwise choose the intended contact property.

HubSpot supports Single-line text, Dropdown select, Multiple checkboxes, Number and Date picker property types in forms. It also supports Multi-line text, Phone number, Single checkbox, Radio select, File, Email and Date and time picker; Calculation, Rollup and Property sync are listed as unsupported. Match the form field to the destination property's type and options.

In HubSpot, go to More > Marketing > Forms, or Marketing > Forms if More does not appear. In the form editor, connect each field to an existing property or create a new one; check whether it is a contact or company property. A company property may create or update an associated company record when the form is submitted.

Check types, defaults and identity

A free-text answer may not fit a controlled list. For a Dropdown select, Multiple checkboxes or Radio select field, align the form choices with the property's options and decide what an “Other” answer should mean.

For blank answers, note whether you intend to retain an existing value or clear it, then test the result on a submitted record. The form's actual behaviour should be verified rather than assumed.

A HubSpot hidden field can set a property from a default value or information in a query string or page URL. Required fields cannot be hidden, and pre-population for returning visitors may overwrite a hidden value depending on the property's field type.

For a hidden field's default, enter a value for Date picker, Number, Single-line text or Multi-line text; choose options for Dropdown select, Multiple checkboxes or Radio select; or select Yes, No or No value for Single checkbox. Check the submitted record to confirm the value arrived.

HubSpot forms can create or update CRM records. On a repeat submission, compare the resulting record ID and mapped values to verify what happened; the field map alone does not establish which record a submission will update.

Trace a submission

To check the configuration, go to More > Marketing > Forms, or Marketing > Forms if More does not appear, and open the form. After submitting a controlled test, open the resulting contact record in the CRM and compare its mapped property values with the answers submitted; check the associated company record too if a company property was used.

Use a controlled new contact to test creation and each mapped value. Submit again with one changed answer under the identity conditions the form will encounter in practice, then compare the resulting record ID and values. Include a blank optional field and an unexpected choice if the form permits one, and record the submission and resulting record ID.

If a value lands on the wrong object or an old value remains, recheck the field connection, defaults, pre-population and contact matching separately. If the submitted CRM record is correct but a value differs after a downstream sync, investigate that sync separately.