HubSpot integration guide · Website enquiries to CRM
HubSpot Forms on External Websites: Embed, Collect or API?
Your website can stay where it is. The decision is how its enquiries reach HubSpot: add a HubSpot form, let HubSpot collect an eligible existing form, or send a custom form’s data through the Forms API. Start with the form you actually have, then check the saved submission and CRM fields.
Embed, collect or use the API: compare the integration routes
Choose according to how much control you need over the form. A website’s brand name or hosting provider is less informative than its actual markup, rendering and submission process.
Add a HubSpot form
Best starting point: a contact or demo page where you can paste an embed and use HubSpot’s form editor.
Check before choosing: the editor generation, design requirements and published domain.
Follow the embed route →Keep a supported HTML form
Consider when: you want to keep a simple form already on the page.
Check before choosing: initial HTML, input types, JavaScript handlers and field mapping.
Check eligibility →Send custom form data
Consider when: the site needs a custom interface or explicit control over the submission request.
Check before choosing: authentication, validation, target form and error handling.
Assess the API route →We suggest choosing the smallest route that meets your requirements. If your current form provider already offers a supported HubSpot integration, assess its field handling before commissioning a custom API build. Automatic collection and an explicit provider integration are different mechanisms.
How to embed a HubSpot form on an external website
You do not need to move your website into HubSpot to embed a form. HubSpot provides an embed code for external pages and a standalone share link.
- Open Marketing → Forms, edit the intended form, and publish or update it.
- Choose Get embed code and copy the code from the Embed code tab. In another documented interface, use Actions → Share → Embed code from the forms list.
- Paste it into the external page’s HTML or embed module.
- Install HubSpot’s tracking code for embedded-form analytics. Add the external site domain in the tracking settings.
- Open the published URL and run the verification exercise below.
Source: the alternative Share menu for finding embed code.
Does the new editor support raw HTML and custom CSS?
The updated editor does not offer the legacy editor’s raw HTML setting. Its advanced developer code, which supports external CSS customisation, requires Marketing Hub or Content Hub Professional or Enterprise. That requirement concerns advanced developer code, not every standard embed.
Source: embed steps, analytics requirements and editor differences.
Our implementation advice: copy the current code from the account instead of reconstructing it from an old tutorial. Keep a note of the account, form and page involved so a later edit can be traced to the right asset.
Can HubSpot collect submissions from your existing HTML form?
Yes, if the form meets the non-HubSpot collection requirements. The tracking code must load and collection must be enabled. In HubSpot settings, open Marketing → Forms → Non-HubSpot Forms and enable Collect data from website forms.
Do not confuse an eligible external form with every form displayed on an external website. HubSpot’s FAQ identifies these common blockers:
- Missing
<form>tags or a form inside an iframe. - An email field that is not
type="email", or no standard<input type="submit">. - JavaScript bound to submission or the submit-button click.
- A form introduced after initial loading, or a single-page application.
- Sensitive fields; hidden-field data is not collected.
Source: non-HubSpot form compatibility and detection.
Why might a submission be partial or a property stay empty?
Collection can record a submit-button click before external validation succeeds, producing partial attempts. Field-to-property matching is automatic, cannot be manually mapped in this tool, and supports single-line text properties. An unmatched value can remain in the submission without appearing on the contact record.
Source: collection behaviour and property mapping.
A concrete field-mapping check for a SaaS demo request
Our example requirement is simple: identify the person, their company and their product interest. Agree on the destination for each value before selecting the integration.
| Website value | Intended destination | What to inspect |
|---|---|---|
| Email address | The contact’s default Email property | The expected contact identity, including an existing contact |
| Company entered as text | An explicitly chosen contact or company property | A text value on a contact does not by itself prove a company association was created |
| Product interest | A property you have created or selected, with an agreed type | The exact value saved; do not assume automatic collection can populate every property type |
| Marketing email choice | The intended email subscription consent configuration | Inspect subscription status separately from a custom checkbox or contact creation |
This is a proposed specification, not a claim that every integration performs these mappings automatically. Decide who owns each field and which later submissions may update it.
What about React, single-page applications and websites built with AI?
Inspect the implementation before choosing. An AI website builder can produce static HTML, a client-rendered application or a form connected to another service. “Built with AI” does not establish which route is compatible.
A demo request form appears only after opening a modal
Our suggested decision process: check when the form enters the page, whether navigation reloads the document, and which code handles its submit event. If those behaviours conflict with automatic collection, evaluate an embedded form mounted correctly by the application or an explicit submission integration.
HubSpot’s documented SPA and late-loading restrictions apply to automatic non-HubSpot collection. They do not establish a universal ban on using HubSpot with React.
Source: why automatic collection can miss dynamically rendered forms.
For an embedded form, HubSpot separately recommends checking JavaScript conflicts, duplicate form IDs and site builders that re-render the container. An embed still needs correct implementation in a dynamic application.
Source: external embed troubleshooting.
Our test recommendation: check a direct page load, navigation from another route, reopening a modal and the mobile layout. Confirm one intended form instance appears in each case. These are acceptance checks to perform on your site, not a compatibility certification for a framework or builder.
Which submission event should a developer use?
For forms made with the updated editor, HubSpot documents hs-form-event:on-submission:success and hs-form-event:on-submission:failed. These differ from legacy callbacks. A button click or the form-ready event does not confirm submission success.
The current events identify formId and instanceId; getConversionId() is available after successful submission. HubSpot says to register an on-ready listener before the embed executes to avoid missing it.
Source: updated-editor events and form instances.
Our recommendation: agree whether a measurement represents a click, an accepted submission or a saved lead. Count the intended outcome once. The event reference is for implementation; this article does not install a tracker or a live HubSpot form.
When should you use the HubSpot Forms API?
Consider the API when you need to preserve a custom form and explicitly control what it sends. HubSpot documents an unauthenticated submission endpoint supporting cross-origin AJAX requests and a separate authenticated endpoint with higher rate limits.
Source: unauthenticated form submissions and CORS.
Source: authenticated form submissions.
The submission payload supports fields and context such as pageUri, pageName and hutk, along with legalConsentOptions. The target uses the HubSpot portal ID and form GUID. Consult the current endpoint definition for the exact payload your implementation needs.
Source: submission payload reference.
An illustrative payload for the public submission endpoint
This example shows the data shape for a contact email and first name. It is not a complete production implementation: use the correct account and form, include its required fields, and implement the applicable consent settings.
{
"fields": [
{
"objectTypeId": "0-1",
"name": "email",
"value": "person@example.com"
},
{
"objectTypeId": "0-1",
"name": "firstname",
"value": "Alex"
}
],
"context": {
"pageUri": "https://example.com/request-demo",
"pageName": "Request a demo"
}
}Send the JSON to the public v3 submission endpoint with your portalId and formGuid. Do not send the literal example address. The omitted tracking token is discussed below; inventing one would not reproduce a visitor’s history.
Source: submission request schema.
Why can the same fields behave differently on the public and secure endpoints?
HubSpot’s developer amendment says new unauthenticated integrations submitting an unlisted CRM property can receive FIELD_NOT_IN_FORM_DEFINITION. It also documents historical exceptions. The secure endpoint can accept existing CRM properties outside the form definition; that does not remove the integrator’s responsibility to validate incoming fields.
HubSpot still recommends including submitted fields in the form definition. Our recommendation is to maintain an explicit field allowlist for either route, especially when an authenticated server endpoint accepts public website input.
Source: developer announcement explaining endpoint-specific validation.
The current API reference marks skipValidation as deprecated, even though generated examples still display it. Our example deliberately omits it. Diagnose a rejected request from its actual response rather than copying an old validation-bypass parameter.
Source: deprecated parameter and response definitions.
A developer handoff that defines the result
Our suggested brief for a developer is deliberately more specific than “connect the form to HubSpot”:
Target: identify the intended HubSpot account and form.
Data: list the website fields, corresponding property names and accepted values.
Request: choose the submission endpoint and authentication approach; keep private credentials on the server.
Outcome: show success only after the request is accepted; explain failures and define how to handle a retry without accidental duplicate sends.
Verification: retain a redacted result showing the form submission and intended CRM properties.
Can the Forms API and automatic collection record the same enquiry twice?
Yes. HubSpot’s community FAQ describes one browser submission being captured automatically and also sent through the API, producing two form submissions for one contact.
Source: the warning about combining both collection paths.
Our diagnostic: compare timestamps and form identities, then inspect whether both mechanisms are active. Choose one intended collection path for the form. Before changing an account-wide collection setting, inventory other website forms that may depend on it.
Check CAPTCHA before adopting the API route
HubSpot states that submissions through the Forms API or other form integrations are not accepted when CAPTCHA is enabled on the target form. Decide the route and its anti-spam design together. Do not switch off protection on a production form merely to make a failing request succeed.
Source: CAPTCHA restrictions for API submissions.
For a custom implementation, our recommendation is to document validation, abuse protection and the visitor-facing error state as part of the same delivery. A working request in a development console is only one part of a usable form.
A lead arrived, but its visit history or email consent did not: what is missing?
Receiving an enquiry, linking earlier page views and subscribing someone to marketing email are separate outcomes. Verify the one you actually need.
Page context and the visitor cookie solve different problems
HubSpot documents that a server-side or proxy submission without the tracking cookie may not be associated with previous visits. A contact can also convert without accepting cookies while having no recorded page-view activity. Shared-browser tests can mix identities or overwrite properties, depending on the form configuration.
Source: cookies, server-side submissions and shared-device identity.
For our example demo request, record the page URL and page name, then check whether the actual visitor token is available under the site’s tracking configuration. Do not insert a fabricated hutk or treat adding pageUri as proof that the whole browsing history was recovered. Test contact identity in a fresh browser session when required.
A checkbox value is not automatically marketing email consent
HubSpot’s form consent options connect communication choices to subscription types. Under the documented separate-consent setup, a submission may be accepted without subscribing the contact to communications when the communication checkbox is not selected. The processing-consent requirement is separate.
Source: form consent options and subscription types.
Our acceptance check: use fresh test contacts, make each intended communication choice and inspect the matching subscription status. For an API build, specify how the visible visitor choice populates the consent payload. Saving “yes” in an unrelated custom property is not evidence that the subscription configuration was applied.
How to verify that a website enquiry actually reaches HubSpot
Check both the submission and the saved CRM record. A thank-you message on the website is not sufficient evidence that all intended data arrived. The following is our proposed acceptance exercise.
- Write the expected result first. Choose a test address you control and harmless values you can recognise. List the intended form, contact and properties. Decide whether this is a new-contact or existing-contact scenario.
- Use the published page. Submit once from the real external URL. Record the time, page and integration route.
- Inspect the form submission. Find that attempt in HubSpot and compare its values with what you entered. Check that one deliberate send did not create two entries through different collection paths. Inspect spam submissions if it is absent from the expected view.
- Inspect the contact. Open the matching record and compare every required property. Check that existing values were not unintentionally overwritten. Inspect visit history and any required subscription status separately.
- Try an invalid entry. Leave a required field incomplete. Confirm what the website displays and whether anything was recorded. Then make one valid submission and inspect the result.
- Repeat after navigation. If your site has client-side routes or modals, repeat from that journey. Check the form remains usable on a phone-sized screen.
- Check the handoff. If you require a notification or follow-up, verify that result separately and assign responsibility for handling the enquiry.
HubSpot forms can connect fields to CRM properties. Its form settings can also determine whether new contacts are marketing contacts, where that feature is available. Review that setting explicitly rather than treating lead capture, marketing status and follow-up as one operation.
Source: form properties and contact settings.
Keep a short record: page, route, expected value, observed value, time and owner. Reuse it after a form edit or website release. This makes a regression easier to isolate than an informal “it worked once”.
The form appears to work, but a lead or field is missing: what should you check?
- “The enquiry landed in spam.”
- For an embedded form, check the exact submission domain in the spam details and add the correct trusted site domain. Some builders submit through a helper or iframe domain. Review legitimate submissions after correcting the setting.
- “I cannot find my existing form in HubSpot.”
- A non-HubSpot form appears in the forms index only after a first submission is captured. Check eligibility and tracking before assuming the form must be created manually in that index.
- “The submission exists, but its page information is absent.”
- Review the integration payload and page context. HubSpot lists missing page parameters in Forms API submissions among possible causes of missing page information.
- “The embedded form is blank or breaks after a website update.”
- Compare the live code with the code supplied by HubSpot. Check script conflicts, CSP or mixed-content issues, duplicated form IDs and dynamic re-rendering of the container.
Source: embedded form troubleshooting checks.
- “The API reports an error, but the site shows success.”
- Our recommendation: make the visible state depend on the actual response. Preserve a redacted error and timestamp for diagnosis; distinguish a validation error from a rate-limit response before choosing a retry strategy.
Source: documented responses, including errors and rate limiting.
If the form is received but a later notification or email fails, isolate that downstream step. Do not rebuild a working collection method before identifying where the journey stops.
Common questions about HubSpot forms on external websites
Do I have to host my website on HubSpot?
No. HubSpot documents an embed for external pages and a separate standalone share link. Your page can remain on its current host.
Can I convert a detected non-HubSpot form into a HubSpot form?
HubSpot provides Actions → Copy to HubSpot for a detected external form. After reviewing and publishing the copied form, replace the website’s old form with its embed. Copying inside HubSpot alone does not replace the website code.
Source: conversion and replacement steps.
Does every Forms API integration need a private access token?
No. HubSpot documents both unauthenticated and authenticated submission endpoints. Select the route deliberately; do not expose a private token in website code.
Is an embedded form the same as a non-HubSpot form?
No. An embed displays a form created in HubSpot. Non-HubSpot collection detects a supported form built outside HubSpot. Their requirements and field handling differ.
Does adding a tracking script guarantee that every enquiry reaches the CRM?
No. Automatic collection depends on supported form behaviour and a successfully loaded script. Verify an actual submission and its saved fields instead of treating script installation as the completed integration.
References for these technical answers: external embeds, existing-form collection and the unauthenticated endpoint.
Method and related HubSpot guides
This guide uses official HubSpot help and developer documentation checked October 18, 2026. The decision process, handoff brief and acceptance exercise are our recommendations. No authenticated HubSpot submission or framework benchmark was performed for this article.
For product features, editions and costs, read our HubSpot review. To work with CRM records from a conversation, use our HubSpot ChatGPT connector guide. For selecting a separate landing-page tool, see our Leadpages review.