Submit data to a form


Method Details

HTTP Methods:


Content Type:


Response Format:


Requires Authentication?


Rate Limited?






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 portal by going to the Contacts > Forms page.

We suggest that you create a unique form within HubSpot to parallel your custom website form. This will make it easy to track submissions on that particular custom form in the future. 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 Contacts > Forms from the navigation menu > click to edit a specifc form > when editing a specific form, you can find the Form GUID in the URL. In the URL, the form GUID is 78c2891f-ebdd-44c0-bd94-15c012bbbfbf

Please Note You should also note that the HS Context and HubSpot tracking cookie listed as optional parameters are very important to users - they provide additional context about the form submission and the user submitting the form. While optional, you should pass these parameters in whenever possible for the best customer experience.

Required Parameters How to use Description
Portal ID Used in the request URL The HubSpot Portal the form belongs to
Form GUID Used in the request URL The GUID for the form
Optional Parameters How to use Description
Email Address &email=x - Used in the request body The email address of the user filling out the form. While an email is not required, HubSpot will not create a contact without a valid email address. Please see this page for more details about how the email address will be validated.
Form Fields &{property key}=x - Used in the request body You can include any number of Contact Properties in the form data. Use the name for the property (contained in the "name" value when looking up your properties via the Contact Properties API)
HS Context &hs_context=x - Used in the request body A JSON formatted block that contains contextual information for the form submission. See the following entries for descriptions of the included data, and below for the format of this parameter.
HubSpot tracking cookie "hutk":x - Used in the hs_context parameter The tracking cookie token value used for HubSpot lead activity tracking. You can retrieve this value from the "hubspotutk" cookie placed in the user's browser by the HubSpot JavaScript Tracking Code; the tracking code must be installed on the page that contains the form.
Please Note While the hutk value is not required for the submission to be accepted, this token is used to associate analytics data with a contact record, so without this you will not see any page views or analytics source data for the contact record.
IP Address "ipAddress":x - Used in the hs_context parameter The IP Address of the lead converting. You can retrieve this from the server request.
Page URL "pageUrl":x - Used in the hs_context parameter The URL the form is submitted on.
Page Name "pageName":x - Used in the hs_context parameter The Name or Title of the page the form is submitted on.
Redirect URL "redirectUrl":x - Used in the hs_context parameter The url to redirect the visitor to. This value must be an absolute URL that includes the protocol (http:// or https:// as the case may be).
Please Note If you have a redirect URL set up for the form in the UI, it will override this option, even if no redirect URL is included in the form POST.
Salesforce Campaign "sfdcCampaignId":x - Used in the hs_context parameter The record ID of the Salesforce Campaign that you want to assign to contacts filling out this form. Only applies to customers using the HubSpot SFDC connector.

Example URL:

Please Note Your content type that you pass in the header of your request should be 'application/x-www-form-urlencoded'.

Example request body for this API call:

  1. firstname=TestContact&lastname=FormSub&

The response from this API call will depend on how the call is made. If there is no "redirectUrl" value in the hs_context parameter, then the response will be as follows:

  • 204 when the form submissions is successful
  • 302 when the form submissions is successful and a redirectUrl is included or set in the form settings.
  • 404 when the Form GUID is not found for the provided Portal ID
  • 500 when an internal server error occurs