Submit data to a form

POST https://forms.hubspot.com/uploads/form/v2/:portal_id/:form_guid

Method Details

HTTP Methods:

POST

Content Type:

application/x-www-form-urlencoded

Response Format:

N/A

Requires Authentication?

No

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing

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 specific form > when editing a specific form, you can 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

Notes
  • While email is listed as optional, contacts will only be created when an email address is included in the submission
  • While hs_context is listed as optional, it includes meta-data 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.
  • 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.
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.
Please Note If no IP address is provided, the IP address of the submission will automatically be set to the IP of the system making the request to the Forms API, which could mean the IP of your server will be used.
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:  https://forms.hubspot.com/uploads/form/v2/62515/78c2891f-ebdd-44c0-bd94-15c012bbbfbf

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:

firstname=TestContact&lastname=FormSub&email=formsub@hubspot.com&newcustomproperty=testing&hs_context=%7B%22hutk%22%3A%2260c2ccdfe4892f0fa0593940b12c11aa%22%2C%22ipAddress%22%3A%22192.168.1.12%22%2C%22pageUrl%22%3A%22http%3A%2F%2Fdemo.hubapi.com%2Fcontact%2F%22%2C%22pageName%22%3A%22Contact%2BUs%22%2C%22redirectUrl%22%3A%22http%3A%2F%2Fdemo.hubapi.com%2Fthank-you%2F%22%7D

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