How to connect your website forms to HubSpot

Three ways to connect a form

All three create or update a contact in HubSpot. The differences are how much control you have over the form and how reliably the lead's source is kept.

Option 1: Embed a HubSpot form

Build the form in HubSpot, then paste its embed code into your page. HubSpot handles validation, spam protection, consent checkboxes and follow-up email.

• Good: no code beyond the embed, and fields map to properties automatically.

• Watch out for: limited control over the design, and an extra script on the page, which can slow it down if you're careful about performance.

Option 2: Capture your existing forms

If your site already loads the HubSpot tracking code, HubSpot can collect submissions from forms it didn't build. Turn on non-HubSpot form collection in your HubSpot form settings, submit each form once, and check the fields map to the right properties.

• Good: no change to your forms.

• Watch out for: it needs a standard HTML form on the page, so it can't see forms inside iframes and can miss forms built entirely in JavaScript. You also get less control over which field maps to which property.

Option 3: Send submissions to the Forms API

Keep the form in your own code, and post each submission from your server to HubSpot's form submission endpoint. This is what we use on custom-built sites, including this one.

// Runs on your server after you validate the submission
const res = await fetch(
  `https://api.hsforms.com/submissions/v3/integration/submit/${portalId}/${formGuid}`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      fields: [
        { objectTypeId: "0-1", name: "email", value: email },
        { objectTypeId: "0-1", name: "firstname", value: firstName },
        { objectTypeId: "0-1", name: "company", value: company },
      ],
      context: {
        hutk, // the visitor's hubspotutk cookie, if they accepted tracking
        pageUri, // the page the form was on
        pageName,
      },
    }),
  },
);

Create a matching form in HubSpot first, because its ID tells HubSpot which form the submission belongs to and the submission appears under it in reports. The objectTypeId of 0-1 means a contact property.

• Good: your design, your validation, and you decide exactly what's sent.

• Watch out for: you must pass the tracking context yourself, and handle errors so a lead isn't lost if the request fails.

Keep the lead's source intact

HubSpot attributes a contact to the source that brought them to your site, such as organic search, paid search or a social post, by linking the submission to the visitor's browsing history. That link is the hubspotutk cookie set by the tracking code.

• With embedded forms and captured forms, HubSpot sends it for you.

• With the Forms API, read the cookie and send it as hutk in context, along with the page URL and title.

• If the visitor declined tracking cookies, don't send it. The contact is still created, just without the browsing history.

UTM parameters are worth capturing too. Store them in hidden fields mapped to contact properties, so campaign details are on the record even when cookies aren't.

Before you go live

• Consent. Record whether the person agreed to marketing email. In Canada, CASL requires consent before you send it.

• Spam. Add a honeypot field or a CAPTCHA, and validate on the server, not only in the browser.

• Errors. If HubSpot doesn't respond, log the submission or retry, so the lead isn't lost.

• Test the whole path. Submit each form, then check the contact record: properties filled, original source correct, owner assigned and any follow-up workflow triggered.

Once leads arrive, they need to reach the right person: see how to set up lead routing in HubSpot. Every website we build comes with forms connected this way, as part of our websites service.