This endpoint is used to send form submission data to HubSpot. Form submissions from external sources can be made to any registered HubSpot form. You can see a list of forms on your account by navigating to Marketing > Lead Capture > Forms.
We recommend creating a unique form in HubSpot to parallel your custom website form, which will make it easy to track future submissions. More information can be found here.
The Form GUID can be found in one of two ways. First, you can pull a list of contact forms using the Forms API, as documented here.
You can also find the Form GUID in the HubSpot UI: navigate to Marketing > Lead Capture > Forms from the navigation menu. When you click to edit a specific form, you'll find the Form GUID in the URL. In the URL https://app.hubspot.com/forms/62515/78c2891f-ebdd-44c0-bd94-15c012bbbfbf/edit/, the form GUID is 78c2891f-ebdd-44c0-bd94-15c012bbbfbf.
This endpoint has a rate limit of 50 requests per 10 seconds. If you require a higher rate limit, you can use the authenticated version of this endpoint. You can find the details for that endpoint here.
As this API is not authenticated, it is necessary to list the submitted form fields in the definition beforehand. This can be configured in the editor or via the API. Failing to do so will result in a FIELD_NOT_IN_FORM_DEFINITION error. To resolve this error, please try the following:
- Use the Submit data to a form (Supporting Authentication) API instead.
- Stop sending this field in the submission
- Add this field to the form definition
- Form fields will correspond to contact properties set up for the HubSpot account. Please see the Contacts API and Contact Properties API for more details.
- When updating a property to have multiple values, separate each value with a semicolon, e.g.
- While email is listed as optional, contacts will only be created when an email address is included in the submission.
- Forms with the CAPTCHA setting enabled are not supported by this endpoint, and you will receive an error for any requests sent for a form with it. Any spam or visitor validation should be performed as part of your form processing before sending the data to HubSpot, as no spam validation will be performed on submissions coming through this endpoint.
- While hs_context is listed as optional, it includes metadata for the form submission that HubSpot uses to provide additional data about contacts:
- The hutk parameter is used to associate analytics data with your contacts. Without this, page views and the original source will not be populated.
- The ipAddress is used to populate the ipaddress property of the contact, which is used to populate the IP City, Country, State/Region properties of the contacts. Note: if no ipAddress is included, the IP address will be set to the IP of the system making the request to the Forms API, which could be your server. Additionally, HubSpot will ignore an IP address from a reserved block (e.g. 127.0.0.0/8).
- The Forms API does not perform any validation on the fields included in the submission data. Any validation needs to be performed before the data is sent in the POST request.
- The validation options set in HubSpot in the form settings will only affect embedded forms.
- This endpoint does not support CORS AJAX requests. See this article for more details.