There's a new version of the HubSpot API
As of November 30, 2022, HubSpot API Keys are being deprecated and are no longer supported. Continued use of HubSpot API Keys is a security risk to your account and data. Your API Keys could be deactivated at any time after Nov. 30th, and we recommend that you migrate to Private Apps as soon as possible so you do not lose business-critical functionality.
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 need complete control over the styles and actions of your form, you can use the Forms API. For more on how to generate an embed code on a form, check out HubSpot's Knowledge Base. For information on how to use the form that this embed code generates, please see the developer documentation.
Please Note 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 | Types | Description |
---|---|---|
portalId | R, I | User's portal ID |
formId | R, I | Unique ID of the form you wish to build |
target | O | jQuery style selector specifying an existing element on the page into which the form will be placed once built. NOTE: If you're including multiple forms on the page, it is strongly recommended that you include a separate, specific target for each form. |
redirectUrl | O, I | URL to which the form will redirect upon a successful form completion. Cannot be used with inlineMessage. |
inlineMessage | O, I | Inline message to display in place of the form upon a successful form completion. Cannot be used with redirectUrl. |
pageId | O, I | ID of the landing page on which the form exists. This must be the content ID of a landing page built in HubSpot. |
cssRequired | O, I | CSS string specific to validation error messages and form styling. Empty string == no style. Note: when setting/declaring this field in the embed code, elements of your form will no longer have default HubSpot styling applied. |
cssClass | O | CSS class that will be applied to the form. |
submitButtonClass | O, I | CSS class that will be applied to the submit input instead of the default .hs-button.primary.large. |
errorClass | O, I | CSS class that will be applied to inputs with validation errors instead of the default .invalid.error. |
errorMessageClass | O, I | CSS class that will be applied to error messages instead of the default .hs-error-msgs.inputs-list. |
groupErrors | O | Show all errors at once inside a single container. Defaults to true, otherwise only shows the first error for each field. |
locale | O | Locale for the form, used to customize language for form errors and the date picker. See Add internationalized error messages below. |
translations | O | An object containing additional translation languages or to override field labels or messages for existing languages. See Customize internationalization below. |
manuallyBlockedEmailDomain | O, I | Array of domains to block in email inputs. |
formInstanceId | O, I | When embedding the same form on the same page twice, populate this Id for each identical form embed. The Id value is must be in string format, using a number instead of a string can result in issues when submitting the form. The Id value used is arbitrary, so long as it is not the same between forms. |
onBeforeFormInit | O, C | Callback that executes before the form builds, takes form configuration object as single argument: onBeforeFormInit(ctx) |
onFormReady | O, C | Callback that executes after form is built, placed in the DOM, and validation has been initialized. This is perfect for any logic that needs to execute when the form is on the page. Takes the jQuery form object as the argument: onFormReady($form) |
onFormSubmit | O, C | Callback that executes after form is validated, just before the data is actually sent. This is for any logic that needs to execute during the submit. Any changes will not be validated. Takes the jQuery form object as the argument: onFormSubmit($form). Note: Performing a browser redirect in this callback is not recommended and could prevent the form submission |
onFormSubmitted | O, C | Callback the data is actually sent.This allows you to perform an action when the submission is fully complete, such as displaying a confirmation or thank you message. |
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 |
required | Please complete this required field. |
invalidEmail | Please enter a valid email address. |
invalidEmailFormat | Email must be formatted correctly. |
invalidNumber | Please enter a valid number. |
invalidNumberRangeTooSmall | Please enter a number that's greater than or equal to {{ min }}. |
invalidNumberRangeTooLarge | Please enter a number that's less than or equal to {{ max }}. |
missingOptionSelection | Please select at least one option. |
missingSelect | Please select an option from the dropdown menu. |
forbiddenEmailDomain | Please enter your business email address. This form does not accept addresses from {{ domain }}. |
forbiddenEmailDomainGeneric | Please enter your business email address. This form does not accept addresses from that domain. |
manuallyBlockedEmailDomain | Please enter a different email address. This form does not accept addresses from {{ domain }}. |
emailOptIn | Please check your email to opt back in. |
resubscribeMessage | Looks like you've opted out of email communication. Click here to get an email and opt back in. |
invalidDate | Please use the datepicker to match the {{ format }} format. |
phoneInvalidCharacters | Must contain only numbers, and the following symbols: + ( ) . - x |
phoneInvalidCharactersWithoutCountryCode | Must contain only numbers, and the following symbols: + ( ) . - x |
phoneInvalidRangeTooShort | Please enter a phone number that's at least { min } numbers long. |
numbersOutOfRange | The number you entered is not in range. |
inputTooLarge | Please use fewer than 65536 characters. |
emailSuggestion | Did you mean {{ email }}? |
invalidDomain | Please enter a valid domain name and try again. |
invalidCaptcha | The Captcha you entered is invalid. Please try again. |
valueNotInFieldDefintion | Please choose one of the provided values. |
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 |
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.MISSING_REQUIRED_FIELDS | Please complete all required fields. |
submissionErrors.OUT_OF_DATE | This form is no longer current. Please refresh the page and try again. |
submissionErrors.BLOCKED_EMAIL | Please change your email address to continue. |
submissionErrors.SUBMISSION_NOT_ALLOWED | This form cannot be submitted. Please contact the site owner. |
submissionErrors.DELETED | This form is no longer active. 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.TOO_MANY_REQUESTS | There was an issue submitting your form. Please wait a few seconds and try again. |
standaloneErrorPage.title | This form no longer exists. |