Submit data to a form

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

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.

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

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.

SFDC Campaign ID "sfdcCampaignId":{string}
Used in context

If the form is for a portal using the HubSpot Salesforce Integration, you can include the ID of a Salesforce campaign to add the contact to the specified campaign.

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.

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 refelcts 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.
thankYouMessage 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_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 samesubscriptionTypeId.