There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Submit data to a form (Supporting Authentication)

Last updated May 31, 2023

POST https://api.hsforms.com/submissions/v2/post/upload/secure/:portalId/:formGuid

There's also an authenticated version of this endpoint that supports field validation, and our GDPR functionality. Try the v3 endpoint documented here.

Method Details

HTTP Methods:

POST

Content Type:

application/x-www-form-urlencoded

Response Format:

N/A

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing

Required Scope:

forms

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 

Notes
  • 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
OAuth Access Token or Private App Access Token Authorization: Bearer {token} header Used to authenticate the request. Please see this page for more details about authentication.
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://api.hsforms.com/submissions/v2/post/upload/secure/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.
  • 401 when the authentication credentials provided are not correct.
  • 403 when credentials provided are correct but doesn't have permission to submit forms.
  • 404 when the Form GUID is not found for the provided Hub ID.
  • 429 when the rate limit has been reached.
  • 500 when an internal server error occurs.