There's a new version of the HubSpot API

Starting November 30, 2022, API keys will be sunset as an authentication method. 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 September 27, 2022

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

 

HubSpot recommends using the authenticated v3 endpoint documented here. This endpoint has higher rate limits, and does not require listing the submitted form fields in the definition beforehand.

Method Details

HTTP Methods:

POST

Content Type:

application/json

Response Format:

json

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 sent to any regular HubSpot form. A list of forms in your account can be found by navigating to Marketing > Lead Capture Forms.

To accurately track submissions from your external form, we recommend creating a new form in HubSpot to parallel your custom website form.

If you're searching for the legacy x-www-form-urlencoded endpoint, you can find the details for that endpoint here instead.

Before you get started 

Please take note of the following:

  • This endpoint has a rate limit of 50 requests per 10 seconds.
  • When using this endpoint to integrate custom forms with HubSpot, keep in mind that the available endpoints do not log any API calls. Users will need to store their own logs. 
  • 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.
  • The fields in the form must correspond to existing contact properties in your HubSpot account. Learn more about how to create new contact properties. You can also view the Contacts API and Contact Properties API documentation for more details.
  • 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.
  • This endpoint does not support reCAPTCHA. If reCAPTCHA has been enabled on the form, submissions will not be accepted. 
  • 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: 

 

 Required Parameters 

Required parameters How to use Description
Portal ID :portalId
Used in the request URL
The HubSpot account that the form belongs to. Learn how to retrieve your account's details, you can also check your PortalID from within HubSpot
Form ID :formGuid
Used in the request URL
The unique ID of the form you're sending data to. Learn how to find your form's GUID
Field values "fields":[...]
Used in the request body

A list of form field names and the values for those fields, up to 1000 fields can be included.

Each list entry will be an object containing "objectTypeId":{field object},"name":{field name}, and "value":{field value} sets.

Only contact, company, and custom properties can be used with this API, learn more about objectTypeId values and custom objects.  The name for each field must match the name of the property from the [Object] Properties API. Field values should match the format used with the same API. See the example request data for more details.

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.

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

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.

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
[DEPRECATED]
"skipValidation": {boolean}
Used in the request body

Please note: this optional parameter is deprecated


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. You can find a list of errorTypeoptions below. 

 

List of errorType displayed

errortype Description
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. 
ERROR 429 The HubSpot account has reached the rate limit.