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

Last updated January 5, 2023

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.