There's a new version of the HubSpot API

Check out the new API
View Beta Docs

We're also working on a new documentation website, you're invited to check it out and give us your feedback.

Submit data to a form

Last updated January 7, 2025

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


HubSpot recommends using the authenticated v3 endpoint documented here. This endpoint includes additional features such as AJAX support, field validation, higher rate limits, and GDPR functionality. When using the authenticated endpoint, you do not need to list the submitted form fields in the definition beforehand.

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

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 review 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. 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: 

Please note:
  • 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.

Required parameters How to use Description
Portal ID Used in the request URL The HubSpot account 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

Response details

The response 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 submission is successful.
  • 302 when the form submission is successful and a redirectUrl is included or set in the form settings.
  • 400 when there is a client error and the request needs to be modified.
  • 404 when the Form GUID is not found for the provided Hub ID.
  • 429 when the account has reached the rate limit.
  • 500 when an internal server error occurs.

About

Jobs

Learn Inbound

Support

Locations

HubSpot, Inc.
25 First Street, 2nd Floor
Cambridge, MA 02141
European Headquarters
Ground Floor, Two Dockland Central
Guild Street, Dublin 1
Asia/Pacific Office
20 Hunter St, Level 7
Sydney NSW 2000
View our other locations
The hs_context parameter should contain the following data, formatted in JSON. Please Note All parameters must be URL encoded before being passed through the API, including the hs_context parameter. { "hutk": "60c2ccdfe4892f0fa0593940b12c11aa", "ipAddress": "192.168.1.12", "pageUrl": "http://demo.hubapi.com/contact/", "pageName": "Contact Us", "redirectUrl": "http://demo.hubapi.com/thank-you/" }
import requests import json import urllib headers ={} headers["Content-Type"]='application/x-www-form-urlencoded' endpoint = 'https://forms.hubspot.com/uploads/form/v2/428357/12b52ab7-50d8-4df2-a0af-08b6117a5af5?&' #Convert the hs_context dictionary to a string hs_context = json.dumps({ "hutk": "60c2ccdfe4892f0fa0593940b12c11aa", "ipAddress": "192.168.1.12", "pageUrl": "http://demo.hubapi.com/contact/", "pageName": "Contact Us", "redirectUrl": "http://demo.hubapi.com/thank-you/" }) #Build your request body data = urllib.urlencode({ 'email':'test123@gmail.com', 'firstname':'test', 'numerationtest':'a;b;c', 'lastname':'testerson', 'hs_context': hs_context }) r = requests.post( url = endpoint, data = data, headers = headers) print(r.text)
<?php //Process a new form submission in HubSpot in order to create a new Contact. $hubspotutk = $_COOKIE['hubspotutk']; //grab the cookie from the visitors browser. $ip_addr = $_SERVER['REMOTE_ADDR']; //IP address too. $hs_context = array( 'hutk' => $hubspotutk, 'ipAddress' => $ip_addr, 'pageUrl' => 'http://www.example.com/form-page', 'pageName' => 'Example Title' ); $hs_context_json = json_encode($hs_context); //Need to populate these variable with values from the form. $str_post = "firstname=" . urlencode($firstname) . "&lastname=" . urlencode($lastname) . "&email=" . urlencode($email) . "&phone=" . urlencode($phonenumber) . "&company=" . urlencode($company) . "&hs_context=" . urlencode($hs_context_json); //Leave this one be //replace the values in this URL with your portal ID and your form GUID $endpoint = 'https://forms.hubspot.com/uploads/form/v2/{portalId}/{formGuid}'; $ch = @curl_init(); @curl_setopt($ch, CURLOPT_POST, true); @curl_setopt($ch, CURLOPT_POSTFIELDS, $str_post); @curl_setopt($ch, CURLOPT_URL, $endpoint); @curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: application/x-www-form-urlencoded' )); @curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = @curl_exec($ch); //Log the response from HubSpot as needed. $status_code = @curl_getinfo($ch, CURLINFO_HTTP_CODE); //Log the response status code @curl_close($ch); echo $status_code . " " . $response; ?>
using System; using System.Collections.Generic; using System.Linq; using System.Web; using System.Web.UI; using System.Web.UI.WebControls; public partial class _Default: System.Web.UI.Page { protected void Page_Load(object sender, EventArgs e) { // Do Nothing } protected void btnSubmit_Click(object sender, System.EventArgs e) { // Build dictionary of field names/values (must match the HS field names) Dictionary < string, string > dictFormValues = new Dictionary < string, string > (); dictFormValues.Add("firstname", txtFirstName.Text); dictFormValues.Add("lastname", txtLastName.Text); dictFormValues.Add("email", txtEmail.Text); dictFormValues.Add("phone", txtPhone.Text); dictFormValues.Add("company", txtCompany.Text); // Form Variables (from the HubSpot Form Edit Screen) int intPortalID = ; //place your portal ID here string strFormGUID = ""; //place your form guid here // Tracking Code Variables string strHubSpotUTK = Request.Cookies["hubspotutk"].Value; string strIpAddress = System.Web.HttpContext.Current.Request.UserHostAddress; // Page Variables string strPageTitle = this.Title; string strPageURL = System.Web.HttpContext.Current.Request.Url.AbsoluteUri; // Do the post, returns true/false string strError = ""; bool blnRet = Post_To_HubSpot_FormsAPI(intPortalID, strFormGUID, dictFormValues, strHubSpotUTK, strIpAddress, strPageTitle, strPageURL, ref strError); if (blnRet) { pnlSuccess.Visible = true; } else { pnlError.Visible = true; lblError.Text = strError; } } /// /// This helper function sends data to the the HubSpot Forms API /// /// HubSpot Portal ID, or 'HUB ID' /// Unique ID for the form /// Dictionary containing all of the field names/values /// UserToken from the visitor's browser /// IP Address of the visitor /// Title of the page they visited /// URL of the page they visited /// /// public bool Post_To_HubSpot_FormsAPI(int intPortalID, string strFormGUID, Dictionary < string, string > dictFormValues, string strHubSpotUTK, string strIpAddress, string strPageTitle, string strPageURL, ref string strMessage) { // Build Endpoint URL string strEndpointURL = string.Format("https://forms.hubspot.com/uploads/form/v2/{0}/{1}", intPortalID, strFormGUID); // Setup HS Context Object Dictionary < string, string > hsContext = new Dictionary < string, string > (); hsContext.Add("hutk", strHubSpotUTK); hsContext.Add("ipAddress", strIpAddress); hsContext.Add("pageUrl", strPageURL); hsContext.Add("pageName", strPageTitle); // Serialize HS Context to JSON (string) System.Web.Script.Serialization.JavaScriptSerializer json = new System.Web.Script.Serialization.JavaScriptSerializer(); string strHubSpotContextJSON = json.Serialize(hsContext); // Create string with post data string strPostData = ""; // Add dictionary values foreach(var d in dictFormValues) { strPostData += d.Key + "=" + Server.UrlEncode(d.Value) + "&"; } // Append HS Context JSON strPostData += "hs_context=" + Server.UrlEncode(strHubSpotContextJSON); // Create web request object System.Net.HttpWebRequest r = (System.Net.HttpWebRequest) System.Net.WebRequest.Create(strEndpointURL); // Set headers for POST r.Method = "POST"; r.ContentType = "application/x-www-form-urlencoded"; r.ContentLength = strPostData.Length; r.KeepAlive = false; // POST data to endpoint using(System.IO.StreamWriter sw = new System.IO.StreamWriter(r.GetRequestStream())) { try { sw.Write(strPostData); } catch (Exception ex) { // POST Request Failed strMessage = ex.Message; return false; } } return true; //POST Succeeded } }
Partial Class _Default Inherits System.Web.UI.Page Protected Sub Page_Load(sender As Object, e As System.EventArgs) Handles Me.Load 'Do nothing End Sub Protected Sub btnSubmit_Click(sender As Object, e As System.EventArgs) Handles btnSubmit.Click 'Build dictionary of field names/values (must match the HS field names) Dim dictFormValues As New Dictionary(Of String, String) dictFormValues.Add("firstname", txtFirstName.Text) dictFormValues.Add("lastname", txtLastName.Text) dictFormValues.Add("email", txtEmail.Text) dictFormValues.Add("phone", txtPhone.Text) dictFormValues.Add("company", txtCompany.Text) 'Form Variables (from the HubSpot Form Edit Screen) Dim intPortalID As Integer = 'place your portal ID here Dim strFormGUID As String = "" 'place your form GUID here 'Tracking Code Variables Dim strHubSpotUTK As String = Request.Cookies("hubspotutk").Value Dim strIpAddress As String = System.Web.HttpContext.Current.Request.UserHostAddress 'Page Variables Dim strPageTitle As String = Me.Title Dim strPageURL As String = System.Web.HttpContext.Current.Request.Url.AbsoluteUri 'Do the post, returns true/false Dim strError As String = "" Dim blnRet = Post_To_HubSpot_FormsAPI(intPortalID, strFormGUID, dictFormValues, strHubSpotUTK, strIpAddress, strPageTitle, strPageURL, strError) If blnRet Then pnlSuccess.Visible = True Else pnlError.Visible = True lblError.Text = strError End If End Sub ''' ''' This helper function sends data to the the HubSpot Forms API ''' ''' HubSpot Portal ID, or 'HUB ID' ''' Unique ID for the form ''' Dictionary containing all of the field names/values ''' UserToken from the visitor's browser ''' IP Address of the visitor ''' Title of the page they visited ''' URL of the page they visited ''' ''' Public Function Post_To_HubSpot_FormsAPI(ByVal intPortalID As Integer, ByVal strFormGUID As String, ByVal dictFormValues As Dictionary(Of String, String), ByVal strHubSpotUTK As String, ByVal strIpAddress As String, ByVal strPageTitle As String, ByVal strPageURL As String, ByRef strError As String) As Boolean 'Build Endpoint URL Dim strEndpointURL As String = String.Format("https://forms.hubspot.com/uploads/form/v2/{0}/{1}", intPortalID, strFormGUID) 'Setup HS Context Object Dim hsContext As New Dictionary(Of String, String) hsContext.Add("hutk", strHubSpotUTK) hsContext.Add("ipAddress", strIpAddress) hsContext.Add("pageUrl", strPageURL) hsContext.Add("pageName", strPageTitle) 'Serialize HS Context to JSON (string) Dim json As New System.Web.Script.Serialization.JavaScriptSerializer Dim strHubSpotContextJSON As String = json.Serialize(hsContext) 'Create string with post data Dim strPostData As String = "" 'Add dictionary values For Each d In dictFormValues strPostData &= d.Key & "=" & Server.UrlEncode(d.Value) & "&" Next 'Append HS Context JSON strPostData &= "hs_context=" & Server.UrlEncode(strHubSpotContextJSON) 'Create web request object Dim r As System.Net.HttpWebRequest = DirectCast(System.Net.WebRequest.Create(strEndpointURL), System.Net.HttpWebRequest) 'Set headers for POST r.Method = "POST" r.ContentType = "application/x-www-form-urlencoded" r.ContentLength = strPostData.Length r.KeepAlive = False 'POST data to endpoint Using sw As New System.IO.StreamWriter(r.GetRequestStream()) Try sw.Write(strPostData) Catch ex As Exception 'POST Failed strError = ex.Message Return False End Try End Using 'POST Succeeded Return True End Function End Class
.Net test
//require Node modules var https = require('https'); var querystring = require('querystring'); // build the data object var postData = querystring.stringify({ 'email': req.body.email, 'firstname': req.body.firstname, 'lastname': req.body.lastname, 'hs_context': JSON.stringify({ "hutk": req.cookies.hubspotutk, "ipAddress": req.headers['x-forwarded-for'] || req.connection.remoteAddress, "pageUrl": "http://www.example.com/form-page", "pageName": "Example Title" }) }); // set the post options, changing out the HUB ID and FORM GUID variables. var options = { hostname: 'forms.hubspot.com', path: '/uploads/form/v2/YOUR_HUB_ID/YOUR_FORM_GUID', method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Content-Length': postData.length } } // set up the request var request = https.request(options, function(response){ console.log("Status: " + response.statusCode); console.log("Headers: " + JSON.stringify(response.headers)); response.setEncoding('utf8'); response.on('data', function(chunk){ console.log('Body: ' + chunk) }); }); request.on('error', function(e){ console.log("Problem with request " + e.message) }); // post the data request.write(postData); request.end();