There's a new version of the HubSpot API
We're also working on a new documentation website, you're invited to check it out and give us your feedback.
Use the options below to customize a HubSpot form's embed code and edit a default HubSpot form. Before getting started, do take note of the following:
If you want to customize your form to add functionality not otherwise provided by HubSpot, use the methods documented in this article. If you require a more complex use-case and further customization over the styles and actions in your form, it is recommended to use the Forms API.
Learn how to generate an embed code on a form. For information on how to using the generated form, please see the developer documentation.
Please note: HubSpot forms should be loaded using the HubSpot-hosted JavaScript file. Making a copy of the form embed code and self-hosting it is not supported. Any improvements that HubSpot makes to improve security, anti-spam, accessibility, and performance will not propagate to your form if you decide to self-host the HubSpot form embed code.
If you're using jQuery to manipulate the values of form inputs (i.e. using val() or prop()), you must trigger a change event using change() or trigger('change') for the change to properly register.
Examples:
$('input[value="checkbox_1"]').prop('checked', true).change();
$('input[name="firstname"]').val('Brian').change();
If not using jQuery:
input.value = value;
input.dispatchEvent(new Event('input', { bubbles: true }));
For Checkboxes:
input.click()
| Attribute | Type | Types | Description |
|---|---|---|---|
| portalId | Number or String | R | The portal ID of the HubSpot account where you created the form. This is used to retrieve the form definition. |
| formId | String | R | The form's ID, which is used to retrieve the form definition. |
| region | String | O | The region of the portal where the form was created. This is used to retrieve the form definition. Possible values are na1 or eu1. |
| target | String | O | A valid CSS selector string, specifying an existing element on the page into which the form will be embedded. NOTE: If you're including multiple forms on the page, it is strongly recommended that you include a separate, specific target for each form. It's strongly recommended you specify this property, otherwise the form is injected after the script location. |
| redirectUrl | String | O | URL to which the form will redirect upon a successful form completion. Cannot be used with inlineMessage. |
| inlineMessage | String | O | Inline message to display in place of the form upon a successful form completion. Cannot be used with redirectUrl. |
| pageId | Number or String | O | ID of the CMS page that you're embedding the form on. Used to associate form submissions with the page. |
| cssRequired | String | O | CSS string specific to validation error messages and form styling. Set this property to an empty string if you do not want to apply default HubSpot styling to the elements of your form. |
| cssClass | String | O | CSS class that will be applied to the form. |
| css | String | O | A CSS string that, when defined, is used instead of the built-in CSS theme. This can be used for setting your own CSS styling. |
| submitText | String | O | String that overrides the text of the submit button. |
| submitButtonClass | String | O | CSS class that will be applied to the submit input instead of the default .hs-button.primary.large. |
| errorClass | String | O | CSS class that will be applied to inputs with validation errors instead of the default .invalid.error. |
| errorMessageClass | String | O | CSS class that will be applied to error messages instead of the default .hs-error-msgs.inputs-list. |
| locale | String | O | Locale for the form, used to customize language for form errors, the date picker, labels, and links. See the Add internationalized error messages section below. |
| translations | Object | O | An object containing additional translation languages or to override field labels or messages for existing languages. See the Customize internationalization section below. |
| manuallyBlockedEmailDomain | Array | O | Array of domains, specified as strings, to block in email input fields. |
| formInstanceId | String | O | Required when embedding the same form on the same page multiple times. The value you specify here as the ID can be arbitrary, so long as it is not the same between forms. |
| sfdcCampaignId | String | O | Set the Salesforce campaign key to associate form submissions with the campaign. |
| goToWebinarWebinarKey | String | O | Set the GoToWebinar campaign key to enroll form submission contacts to a GoToWebinar webinar. The portal must have the GoToWebinar integration installed. |
| formInstanceId | String | O | Required when embedding the same form on the same page multiple times. The value you specify here as the ID can be arbitrary, so long as it is not the same between forms. |
| onBeforeFormInit | Function | O | Callback that executes before the form builds, takes form configuration object as single argument: onBeforeFormInit(ctx) |
| onFormReady | Function | O | Callback that executes just before the form render. This callback should be used for any logic that needs to execute when the form has fully rendered on the page. Takes the jQuery form object as the argument: onFormReady($form) |
| onFormSubmit | Function | O | Callback that executes after form is validated, before the form is submitted (i.e., right before the data is actually sent). This is for any logic that needs to execute before submission is initiated. Any changes made to form fields will not be validated. Takes the jQuery form object as the argument: onFormSubmit($form). Note: It is not recommended to perform a browser redirect in this callback, as it could prevent the form submission. For any custom redirects, use the onFormSubmitted callback. |
| onBeforeFormSubmit | Function | O | Callback that executes after the form is validated, before the form is submitted i.e. before the data is actually sent. This is for any logic that needs to execute before submission is initiated. Any changes made to fields will not be validated.
. Note: This callback behaves in the same way as onFormSubmit, but is preferred due to the accurate naming of when it is triggered.
Takes the jQuery form object as the argument and an array of submission values: onBeforeFormSubmit($form, submissionValues).
As in the case of onFormSubmit, It is NOT recommended to perform a browser redirect in this callback as this could prevent before the submission is initiated, thus preventing form submissions. For any custom redirects, please use the onFormSubmitted callback. |
| onFormSubmitted | Function | O | Callback that executes after form submission. This is for executing actions when the submission is fully complete, such as displaying a confirmation or thank you message, or performing a custom redirect. The callback's arguments are the form element and an object containing two properties:
onFormSubmitted($form, data)
|
As the default CSS styling is 'stacked', i.e. labels atop inputs, removing the default classes on the form will result in an alignment of inputs to the right of their labels. To accomplish this, simply set your own custom cssClass that does not include the class 'stacked'. View the example in the right code pane.
HubSpot provides a number of custom validation messages in many different languages by default. View the example in the right code pane.
| Key | Language |
|---|---|
| en | English |
| da | Danish |
| de | German |
| es | Spanish (Spain) |
| es-mx | Spanish (Mexico) |
| fi | Finnish |
| fr | French |
| it | Italian |
| ja | Japanese |
| nl | Dutch |
| pl | Polish |
| pt-br | Portuguese |
| sv | Swedish |
| zh-cn | Chinese |
| zh-hk | Chinese (Hong Kong) |
You can add custom languages or override the error messages and datepicker months/days displayed on the form by passing language objects into the translations parameter described above.
The embed code expects the format {locale: {messageKey: customMessage}}. You can override field labels by specifying the label as {locale: {fieldLabels: {fieldName: customLabel}}}, and the submit button text using {locale:{submitText: customSubmitText}} See the example in the right code pane.
To override existing messages, just pass in a language object with the desired locale found in the above table. For locales listed in the table above, you only need to provide the keys and messages you wish to override.
It's also possible to register new locale codes to use with the locale parameter. In this case, make sure to specify messages for all of the keys listed in the table below. Omitted keys will show a "missing translation" message in their place.
| Key | English default |
|---|---|
| learnMore | Learn more |
| submitText | Submit |
| previousMonth | Previous Month |
| nextMonth | Next Month |
| january | January |
| february | February |
| march | March |
| april | April |
| may | May |
| june | June |
| july | July |
| august | August |
| september | September |
| october | October |
| november | November |
| december | December |
| sunday | Sunday |
| monday | Monday |
| tuesday | Tuesday |
| wednesday | Wednesday |
| thursday | Thursday |
| friday | Friday |
| saturday | Saturday |
| sundayShort | Sun |
| mondayShort | Mon |
| tuesdayShort | Tue |
| wednesdayShort | Wed |
| thursdayShort | Thu |
| fridayShort | Fri |
| saturdayShort | Sat |
| fallbackDescription | We had some trouble loading this form. |
| fallbackCta | Click here to continue. |
| fallbackGenericDescription | This form didn't load. Please try again later. |
| fileTooLarge | Selected file is too large. Maximum allowed size is 100MB. |
| defaultSelectOptionLabel | Please Select |
| notYou | Not you? |
| resetTheForm | Click here to reset |
Live validation refers to the validation that occurs while a visitor fills out a form. This is not the validation that occurs during submission. If live validation has been turned on in the Hubspot account, client side and server-side validation will run during the visitor experience on the form. The following are the currently supported live validation field error keys for contextual overriding:
| Error key | English default |
|---|---|
| requiredField | Please complete this required field. |
| required | Please complete this required field. |
| missingSelect | Please complete this required field. |
| missingOptionSelection | Please complete this required field. |
| fileTooLarge | Selected file is too large. Maximum allowed size is 100MB. |
| invalidEmailFormat | Email must be formatted correctly. |
| phoneInvalidCharacters | A valid phone number may only contain numbers, +()-, or x. |
| invalidNumber | Please enter a valid number. |
| invalidDate | Please enter a valid date |
| invalidEmail | Please enter a valid email address. |
| invalidNumberRangeTooSmall | Please enter a number that's greater than or equal to . |
| invalidNumberRangeTooLarge | Please enter a number that's less than or equal to . |
| forbiddenEmailDomain | Please enter a different email address. This form does not accept addresses from {{domain}}. |
| manuallyBlockedEmailDomain | Please enter a different email address. This form does not accept addresses from {{domain}}. |
| numberOutOfRange | The number you entered is not in range. |
| inputTooLarge | Please use fewer than 65536 characters. |
Submission validation will run both client-side prior to submission as well as on the server after a submission request has been sent.
The following errors may be generated and displayed client-side.
They can be contextually overridden via submissionErrors property on the context:
| Error Key | English Default |
|---|---|
| submissionErrors.MISSING_REQUIRED_FIELDS | Please complete all required fields. |
| submissionErrors.BLOCKED_EMAIL | Please change your email address to continue. |
| submissionErrors.TOO_MANY_REQUESTS | There was an issue submitting your form. Please wait a few seconds and try again. |
The following errors may be generated on the server after a submission request has been sent
and displayed client-side when a response is received. Similar to client side submission validation errors,
they can be contextually overridden via submissionErrors property on the context:
| Error Key | English Default |
|---|---|
| submissionErrors.SERVER_ERROR | Sorry, something went wrong and the form was not submitted. Please try again later. |
| submissionErrors.RECAPTCHA_VALIDATION_ERROR | Failed to validate Captcha. Please try again. |
| submissionErrors.OUT_OF_DATE | This form is no longer current. Please refresh the page and try again. |
| submissionErrors.FORM_NOT_PUBLISHED | This form is no longer active. Please refresh the page and try again. |
| submissionErrors.MISSING_SCOPE | This form cannot be submitted. Please contact the site owner. |
| submissionErrors.FORM_NEVER_EXISTED | This form cannot be submitted. Please contact the site owner. |
| submissionErrors.FORM_TYPE_MISMATCH | This form cannot be submitted. Please contact the site owner. |
| submissionErrors.FILE_TOO_LARGE | Selected file is too large. Maximum allowed size is 100MB. |