Submit data to a form

Last updated June 17, 2020

POST https://api.hsforms.com/submissions/v3/integration/submit/:portalId/:formGuid

Method Details

HTTP Methods:

POST

Content Type:

application/json

Response Format:

json

Requires Authentication?

No

Rate Limited?

No

Headers

User-Agent

Products:

Marketing

This endpoint is used to send form submission data to HubSpot, including those using AJAX. 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.

We recommend creating a unique form in HubSpot to parallel your custom website form. This will make it easy to track submissions on that particular custom form in the future.

Note: In addition to accepting server-side HTTP requests, this endpoint will accept cross-origin AJAX (CORS) requests, allowing you to submit form data directly to HubSpot client-side using JavaScript.
Note: The fields in the form will correspond to contact properties set up for the HubSpot account. Please see the Contacts API and Contact Properties API for more details.
Note: When backdating a form submission's submittedAt timestamp value, the contact's Original Source value may be affected if the contact's first page view is after the submittedAt timestamp value.

Looking for the legacy x-www-form-urlencoded endpoint? You can find the details for that endpoint here.
Required parameters How to use Description
Portal ID :portalId
Used in the request URL		 The HubSpot portal the form belongs to.
Form ID :formGuid
Used in the request URL		 The ID of the form you're sending data to.
Field values "fields":[...]
Used in the request body

A list of form field names and the values for those fields. Each list entry will be an object containing "name":{field name} and "value":{field value} pairs.

The name for each field must match the name of the property from the Contact Properties API. Field values should match the format used with the Contacts API. See the example request data for more details.

Note: Up to 1000 fields can be included. 
Legal consent options legalConsentOptions: {...}
Used in the request body		 This field is used to indicate that the visitor submitting the form provided their consent for communications and processing. The details included in this field are described below.
Note: This field is required if the form was created on a portal with GDPR functionality enabled and the consent notice information was added to the form.

Optional parameters How to use Description
Context data "context":{...}
Used in the request body		 A set of data containing contextual information for the submission. See the following entries for descriptions of the included data.
HubSpot usertoken "hutk": {string}
Used in context		 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":{string}
Used in context		 The IP address of the visitor filling out the form.
Page name

"pageName":{string}
Used in context

The name or title of the page the submission happened on.
Page URI "pageUri":{string}
Used in context

The URI of the page the submission happened on.
Page ID "pageId":{string}
Used in context		 The ID of a page created on the HubSpot CMS. Including the pageId will cause HubSpot to attribute the submission to a specific HubSpot page, so that the page performance details will record the submission.

Use the CMS Pages API to get the ID of the page you want to track for the form.
SFDC campaign ID "sfdcCampaignId":{string}
Used in context

If the form is for an account using the HubSpot Salesforce Integration, you can include the ID of a Salesforce campaign to add the contact to the specified campaign.
GoToWebinar key/ID "goToWebinarWebinarKey":{string}
Used in context

If the form is for an account using the HubSpot GoToWebinar Integration, you can include the ID of a webinar to enroll the contact in that webinar when they submit the form.

See this page for more details.
Submission timestamp "submittedAt":{timestamp}
Used in the request body

A millisecond timestamp representing the time of the form submission. This can be used to backdate the submission, but using a time more than one month old will result in an error.

NOTE: This field can only be used to backdate a submission, and only for a date up to one month in the past. If you want the submission to use the current time, you should omit this field from the request.
Skip validation "skipValidation": {boolean}
Used in the request body

Whether or not to skip validation based on the form settings. Defaults to false.

Legal consent options

If the form was created with the GDPR notice enabled, the details of those notices must be included in the form submission data. Depending on the option used, you must include one of these fields:

  • consent - Used when the form uses one of the Consent checkbox(es) options.
  • legitimateInterest - Used if the Legitimate interest option is used.

Each of those fields would require the data described below. Please note that any text fields would need to include the text displayed to the visitor. The email subscription type IDs can be pulled from the Email API.

{
  "fields":[...], 
  "legalConsentOptions":{
    "consent":{
      "consentToProcess":true,
      // Boolean; Whether or not the visitor checked the Consent to process checkbox
      "text":"Text that gives consent to process",
      // String; The text displayed to the visitor for the Consent to process checkbox
      "communications":[
      // A list of details for the Consent to communicate for each subscription type included in the form
        {
          "value":true,
          // Boolean; Whether or not the visitor checked the checkbox for this subscription type.
          "subscriptionTypeId":999,
          // Integer; The ID of the specific subscription type
          "text":"Consent to communicate text for subscription type ID 999"
          // String; The text displayed to the visitor for this specific subscription checkbox
        },
        {
           "value":true,
           "subscriptionTypeId":777,
           "text":"Consent to communicate text for subscription type ID 777"
        }
      ]
    }
  }
}
{
  "fields": [],
  "legalConsentOptions": {
    "legitimateInterest": {
      "value": true,
      // This must be true when using the 'legitimateInterest' option, as it reflects the consent indicated by the visitor when submitting the form
      "subscriptionTypeId": 999,
      // Integer; The ID of the specific subscription type that this forms indicates interest to.
      "legalBasis": "CUSTOMER",
      // String, one of CUSTOMER or LEAD; Whether this form indicates legitimate interest from a prospect/lead or from a client.
      "text": "Legitimate interest consent text"
      // String; The privacy text displayed to the visitor.
    }
  }
}

Response details

The response will include the following fields:

redirectUri If the submission was accepted, and the form has a redirect URI set in its settings, this will be that redirect URI.
inlineMessage If the submission was accepted, and the form has an inline thank you message set in its settings, this will the the HTML for that message.
errors

A list of errors with the submission data.

Each entry will contain a message value detailing the specific error, and an coded errorType.

errorType will be one of these options:

  • MAX_NUMBER_OF_SUBMITTED_VALUES_EXCEEDED - More than 1000 fields were included in the response.
  • INVALID_EMAIL - For email fields, the email was not a valid format.
  • BLOCKED_EMAIL - For email fields, the email is blocked by the blocked email list for the form.
  • REQUIRED_FIELD - The field is marked as required but was not included in the submission.
  • INVALID_NUMBER - For number fields, the value was not a number value.
  • INPUT_TOO_LARGE - The value in the field is too large for the type of field.
  • FIELD_NOT_IN_FORM_DEFINITION - The field was included in the form submission but is not in the form definition.
  • NUMBER_OUT_OF_RANGE - The value of a number field outside the range specified in the field settings.
  • VALUE_NOT_IN_FIELD_DEFINITION - The value provided for an enumeration field (e.g. checkbox, dropdown, radio) is not one of the possible options.
  • INVALID_METADATA - The context object contains an unexpected attribute.
  • INVALID_GOTOWEBINAR_WEBINAR_KEY - The value in goToWebinarWebinarKey in the context object is invalid.
  • INVALID_HUTK - The hutk field in the context object is invalid.
  • INVALID_IP_ADDRESS - The ipAddress field in the context object is invalid.
  • INVALID_PAGE_URI - The pageUri field in the context object is invalid.
  • INVALID_LEGAL_OPTION_FORMAT - legalConsentOptions was empty or it contains both the consent and legitimateInterest fields.
  • MISSING_PROCESSING_CONSENT - The consentToProcess field in consent or value field in legitimateInterest was false.
  • MISSING_PROCESSING_CONSENT_TEXT - The text field for processing consent was missing.
  • MISSING_COMMUNICATION_CONSENT_TEXT - The communication consent text was missing for a subscription.
  • MISSING_LEGITIMATE_INTEREST_TEXT - The legitimate interest consent text was missing.
  • DUPLICATE_SUBSCRIPTION_TYPE_ID - The communications list contains two or more items with the same subscriptionTypeId.
  • FORM_HAS_RECAPTCHA_ENABLED - This form has reCAPTCHA enabled so programatic submissions are not allowed. 

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
Example JSON body: { "submittedAt": "1517927174000", // This millisecond timestamp is optional. Update the value from "1517927174000" to avoid an INVALID_TIMESTAMP error. "fields": [ { "name": "email", "value": "example@example.com" }, { "name": "firstname", "value": "Jeff" } ], "context": { "hutk": ":hutk", // include this parameter and set it to the hubspotutk cookie value to enable cookie tracking on your submission "pageUri": "www.example.com/page", "pageName": "Example page" }, "legalConsentOptions": { "consent": { // Include this object when GDPR options are enabled "consentToProcess": true, "text": "I agree to allow Example Company to store and process my personal data.", "communications": [ { "value": true, "subscriptionTypeId": 999, "text": "I agree to receive marketing communications from Example Company." } ] } } }
Example AJAX call using the formv3 endpoint: function formv3(){ // Create the new request var xhr = new XMLHttpRequest(); var url = 'https://api.hsforms.com/submissions/v3/integration/submit/62515/fcc69886-915b-4fef-b35f-27850ef461e1' // Example request JSON: var data = { "submittedAt": "1517927174000", "fields": [ { "name": "email", "value": "example@example.com" }, { "name": "firstname", "value": "Jeff" } ], "context": { "hutk": ':hutk', // include this parameter and set it to the hubspotutk cookie value to enable cookie tracking on your submission "pageUri": "www.example.com/page", "pageName": "Example page" }, "legalConsentOptions":{ // Include this object when GDPR options are enabled "consent":{ "consentToProcess":true, "text":"I agree to allow Example Company to store and process my personal data.", "communications":[ { "value":true, "subscriptionTypeId":999, "text":"I agree to receive marketing communications from Example Company." } ] } } } var final_data = JSON.stringify(data) xhr.open('POST', url); // Sets the value of the 'Content-Type' HTTP request headers to 'application/json' xhr.setRequestHeader('Content-Type', 'application/json'); xhr.onreadystatechange = function() { if(xhr.readyState == 4 && xhr.status == 200) { alert(xhr.responseText); // Returns a 200 response if the submission is successful. } else if (xhr.readyState == 4 && xhr.status == 400){ alert(xhr.responseText); // Returns a 400 error the submission is rejected. } else if (xhr.readyState == 4 && xhr.status == 403){ alert(xhr.responseText); // Returns a 403 error if the portal isn't allowed to post submissions. } else if (xhr.readyState == 4 && xhr.status == 404){ alert(xhr.responseText); //Returns a 404 error if the formGuid isn't found } } // Sends the request xhr.send(final_data) }