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.

Forms API Overview

What is the Forms API?

Inbound marketing involves attracting, engaging, and delighting customers with content that adds value. When doing so, it's recommended to use forms to capture important visitor information. After, you can nurture and convert these visitors into customers. To learn more about the HubSpot forms tool, try it in a test account, or learn more about using HubSpot's forms tool

Use case for this API: While HubSpot has a native forms tool, some users may want to build forms natively on their site or application. Then, pass those form submissions to HubSpot via the API. If you must have a custom user-submitted form for any reason, the Forms API will provide the control you need. For example, forms that do calculations or have custom elements. 

Using the Forms API

The Forms API's principal method is the submit form method. This allows you to pass any information captured on your website or application to HubSpot, including custom data. You can select from two different endpoints:

For security reasons, it's recommended to use the Submit data to a form (Supporting Authentication) endpoint. This endpoint also has a higher rate limit. If you do not wish to use authentication, you can use the Submit data to a form endpoint. When using the Forms API, accessibility and validation are your responsibilities.

There are some limits in place for contact records and form submissions that may affect your testing. Please review the contact and form limits. For questions about the Forms API, refer to our developer forum, where many common questions have already been answered.

When not to use Forms API

The Forms API should not be used in the following instances:

  • To bulk import contacts
  • To update contact properties

Instead, use the contacts batch update for bulk imports. Abuse of the Forms API will result in submissions being ignored until behavior is changed. 

Forms API data

Each form will have the following data. See creating a form and the Contact Properties API Overview for more details on the types of contact properties that can be used and the form fields that they're related to. 

{
  "portalId": 62515,
  // Integer, read-only; The Hub ID that the form belongs to.
  "guid": "62629d4c-df35-479b-995a-467a330922fb",
  // String, read-only; The internal ID of the form
  "name": "Example Form",
  // String; The name of the form
  "action": "",
  // DEPRECATED - This field is no longer used.
  "method": "POST",
  // String, read-only; This will always be POST
  "cssClass": "hs-form stacked",
  // String; The default css classes added to the form when embedded.
  // Can be overridden when embedding the form using the 'cssClass' option.
  "redirect": "",
  // String; The URL that the visitor will be redirected to after filling out the form.
  "submitText": "Submit",
  // String; The text used for the submit button.
  "followUpId": "",
  // DEPRECATED - This field is no longer used.
  "notifyRecipients": "",
  // String; A comma-separated list of user IDs that should receive submission notifications. Email addresses will be returned for individuals who aren't users.
  "leadNurturingCampaignId": "",
  // DEPRECATED - this field is no longer used.
  "formFieldGroups": [
  // A list of field groups. Each group represents a group of fields (displayed as a row when the form is embedded)
    {
      "fields": [
      // A list of fields in the group
        {
          "name": "firstname",
          // String; The name of the field. This needs to match the internal name of a contact property.
          "label": "First Name",
          // String; The label that will appear for the field.
          "type": "string",
          // String, one of string, number, date, datetime, or enumeration
          // This needs to match the 'type' field of the corresponding contact property.
          "fieldType": "text",
          // String, one of textarea, text, date, file, number, select, radio, checkbox, or booleancheckbox
          // The type of field that will be used when the form is embedded.
          "description": "",
          // String; The help text that displays below the label.
          "groupName": "",
          // DEPRECATED - this field is not used.
          "displayOrder": -1,
          // Integer; The order to display the fields in.
          //If the values are negative, the fields appear in the order they appear in the 'fields' list
          "required": false,
          // Boolean; Required fields must be filled out to submit the form.
          "selectedOptions": [],
          // For enumerated fields, this will be a list of Strings representing the options that will be selected by default
          "options": [],
          // For enumerated fields, this will be a list of Strings representing the available options for the field
          // Will be empty for non-enumerated fields.
          "validation": {
          // A set of options controlling the validation for the field
          // NOTE: These options should NOT be modified through the API. Any validation should be set up in the form settings in HubSpot.
            "name": "",
            "message": "",
            "data": "",
            "useDefaultBlockList": false,
            "blockedEmailAddresses": []
          },
          "enabled": true,
          // DEPRECATED - this field is not used.
          "hidden": false,
          // Boolean; When set to true, the field will be rendered as a hidden field.
          "defaultValue": "",
          // String; The default value of the field
          "isSmartField": false,
          // Boolean; Whether or not the field is a smart field.
          // Smart fields are hidden if the visitor is a known contact that already has a value for the field.)
          "unselectedLabel": "",
          // DEPRECATED - this field is not used.
          "placeholder": "",
          // String; The placeholder text for the field, which will display 
          "dependentFieldFilters": [],
          // A list of filters that will be used to display dependent fields.
          "labelHidden": false
          // DEPRECATED - this field is not used.
        },
        {
          "name": "lastname",
          "label": "Last Name",
          "type": "string",
          "fieldType": "text",
          "description": "",
          "groupName": "",
          "displayOrder": -1,
          "required": false,
          "selectedOptions": [],
          "options": [],
          "validation": {
            "name": "",
            "message": "",
            "data": "",
            "useDefaultBlockList": false,
            "blockedEmailAddresses": []
          },
          "enabled": true,
          "hidden": false,
          "defaultValue": "",
          "isSmartField": false,
          "unselectedLabel": "",
          "placeholder": "",
          "dependentFieldFilters": [],
          "labelHidden": false
        }
      ],
      "default": true,
      "isSmartGroup": false,
      "richText": {
        "content": ""
      }
    },
    {
      "fields": [
        {
          "name": "email",
          "label": "Email",
          "type": "string",
          "fieldType": "text",
          "description": "",
          "groupName": "contactinformation",
          "displayOrder": -1,
          "required": true,
          "selectedOptions": [],
          "options": [],
          "validation": {
            "name": "",
            "message": "",
            "data": "",
            "useDefaultBlockList": false,
            "blockedEmailAddresses": []
          },
          "enabled": true,
          "hidden": false,
          "defaultValue": "",
          "isSmartField": false,
          "unselectedLabel": "",
          "placeholder": "",
          "dependentFieldFilters": [],
          "labelHidden": false
        }
      ],
      "default": true,
      "isSmartGroup": false,
      "richText": {
        "content": ""
      }
    }
  ],
  "selectedExternalOptions": 
  // The Customize lifecycle stage based on submissions settings in a form's options.
  // Both entries for contacts and companies must be included or will result in an INVALID_LIFECYCLE_STAGE error.
    	[
		{	
			"referenceType": "PIPELINE_STAGE",
            // String; the value should always be set to PIPELINE_STAGE.
 			"objectTypeId": "0-1",
            // String; the objectTypeId for contacts.
			"propertyName": "lifecyclestage",
            // String; the internal name of the lifecycle stage property
			"id": "marketingqualifiedlead"
            // String; the internal name of the contact's lifecycle stage set when submitting a form.
		},
        {
 			"referenceType": "PIPELINE_STAGE",
            // String; the value should always be set to PIPELINE_STAGE.
			"objectTypeId": "0-2",
            // String; the objectTypeId for companies.
			"propertyName": "lifecyclestage",
            // String; the internal name of the lifecycle stage property.
			"id": "marketingqualifiedlead"
            // String; the internal name of the contact's lifecycle stage set when submitting a form.
		}
	]
  "createdAt": 1500588456053,
  // Integer, read-only; A Unix timestamp (in milliseconds) for when the form was created.
  "updatedAt": 1500588497572,
  // Integer, read-only; A Unix timestamp (in milliseconds) for when the form was last modified.
  "performableHtml": "",
  // DEPRECATED - this field is not used.
  "migratedFrom": "",
  // DEPRECATED - this field is not used.
  "ignoreCurrentValues": false,
  // Boolean; If true, the form will pre-populate fields with known values for know contacts.
  "metaData": [],
  // DEPRECATED - this field is not used.
  "deletable": true,
  // Boolean; If false, the form is a system form (such as a blog comment or subscription form) and cannot be deleted.
  // This will default to true and should also be set to true for forms created through the API.
  "inlineMessage": "",
  // String; A thank you message to display on the page after the form is submitted.
  "tmsId": "",
  // DEPRECATED - This field is no longer used.
  "captchaEnabled": false,
  // Boolean; Will be set to true for forms with captcha enabled.
  // If you're submitting form data through the API, this should be set to false, and any captcha or other spam protection
  // should be implemented in your form before sending the data to HubSpot
  "campaignGuid": "",
  // DEPRECATED - this field is not used.
  "cloneable": true,
  // Boolean; Whether or not the form can be cloned. Forms created through the API should leave this as true (the default).
  "editable": true,
  // Boolean; Whether or not the form can be edited. Forms created through the API should leave this as true (the default).
  "formType": "HUBSPOT",
  // String; This fields is deprecated and will always be HUBSPOT
  "deletedAt": 0
  // Integer, read-only; A Unix timestamp (in milliseconds) for when the form was deleted
  // This will effectively always be 0 as deleted forms are not available through the API.
}

Docs for this section or API