There's a new version of the HubSpot API

We're also working on a new documentation website, you're invited to check it out and give us your feedback.

Submit data to a form (Supporting Authentication)

Last updated September 5, 2023

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

Method Details

HTTP Methods:

POST

Content Type:

application/json

Response Format:

json

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. 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 CaptureForms. 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. This will make it easy to track submissions on that particular custom form in the future.

Looking for the legacy x-www-form-urlencoded endpoint? You can find the details for that endpoint here.

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 

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.
  • While endpoint has a higher rate limit than the unauthenticated v3 Form Submission endpoint, it does not support CORS. If you're sending a CORS request, please use the unauthenticated v3 Form Submission endpoint instead. 
  • 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.
  • 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. 

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

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
[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:

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

The errorType will be one of the following options:

  • MAX_NUMBER_OF_SUBMITTED_VALUES_EXCEEDED: more than 1000 fields were included in the response.
  • 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_DOMAIN: for fields referencing a company's domain, the value is invalid. 
  • INVALID_LEGAL_CONSENT_OPTIONS:   legalConsentOptions  was empty, or the value used does not exist in your HubSpot account.
  • INVALID_TIMESTAMP: for the Submission timestamp property, the input value is invalid. A valid timestamp must be comprised between NOW - 30 days and NOW + 1 minute.
  • 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.
  • PORTAL_NOT_OBJECT_TYPE_OWNER: the CRM Object type for a form field does not exist in the HubSpot portal.

Additional errors that get returned: 

  • 401 when authentication credentials provided are incorrect.
  • 403 when authentication credentials provided are correct but the account doesn't have permission to submit forms.
  • 429 when the account has reached the rate limit.