Method Details
HTTP Methods:
POST
Content Type:
application/x-www-form-urlencoded
Response Format:
N/A
Requires Authentication?
Yes
Rate Limited?
Headers
Products:
Marketing
Required Scope:
This endpoint is used to send form submission data to HubSpot using authentication. It also has a higher rate limit than the unauthenticated v2 Form Submission endpoint.
As this API is authenticated, it is not necessary to list the submitted form fields in the definition beforehand. However, the properties used must still be compatible for use in forms.
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. This endpoint should not be used with non-HubSpot forms. When reviewing your forms, any non-HubSpot form will display a Non-HubSpot form label.
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:
- 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.
- Click a specific form.
- In the form editor, you'll find the Form GUID in the URL.
- For example, if the URL is:https://app.hubspot.com/forms/123456/319478e5-e5fd-4d39-9d13-fc1f90bf46da/performance
- The form GUID is: 319478e5-e5fd-4d39-9d13-fc1f90bf46da.
This endpoint has the following rate limits:
- Free/Starter accounts: 100 requests/10 seconds
- Professional/Enterprise accounts: 150 requests/10 seconds
- Accounts with the API Add On: 200 requests/10 seconds
- 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.
"property_name":"a;b;c"
- 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.