Create a new form

Last updated December 30, 2019

POST /forms/v2/forms

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 create a new form in a given HubSpot account.

Use case for this endpoint: Forms are standard website tools that are used to generate leads. This capability might be useful for an integration with an external system that has its own form-building interface.

Form fields and groups

Forms may have a set of associated fields or field groups. When creating a new form using this API, you can specify the fields that you want included.

Field groups are used to group fields together in a row. All fields in the same fieldgroup will be displayed on the same row.

Response details

All forms should have a unique name. If you attempt to create a new form using the same name as an existing form, we will return a 409.

 

Required parameters How to use Description
OAuth Access Token or API Key Authorization: Bearer {token} header
or hapikey={key} query parameter.		 Used to authenticate the request. Please see this page for more details about authentication.
Form data Used in the request body The data for the form that you're creating. This can include any number of data points or fields. For an example of this data, please see the JSON code sample for POSTing and creating a new form below.
Optional parameters How to use Description
Form fields and groups Used in the request body When creating a new form, you have the ability to also add some fields that you'd like to be a part of the form you're creating. These fields will show up in the form through the HubSpot user interface, where you can customize your forms further. For an example of the data structure for adding form fields to your form on creation with this method, please see the example below.

Example URL:  https://api.hubapi.com/forms/v2/forms?hapikey=demo

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 request body that you need to create a new form through this API call: { "name": "DemoForm", "action": "", "method": "", "cssClass": "", "redirect": "", "submitText": "Submit", "followUpId": "", "notifyRecipients": "", "leadNurturingCampaignId": "", "formFieldGroups": [ { "fields": [ { "name": "firstname", "label": "First Name", "type": "string", "fieldType": "text", "description": "", "groupName": "", "displayOrder": 0, "required": false, "selectedOptions": [], "options": [], "validation": { "name": "", "message": "", "data": "", "useDefaultBlockList": false }, "enabled": true, "hidden": false, "defaultValue": "", "isSmartField": false, "unselectedLabel": "", "placeholder": "" } ], "default": true, "isSmartGroup": false }, { "fields": [ { "name": "lastname", "label": "Last Name", "type": "string", "fieldType": "text", "description": "", "groupName": "", "displayOrder": 1, "required": false, "selectedOptions": [], "options": [], "validation": { "name": "", "message": "", "data": "", "useDefaultBlockList": false }, "enabled": true, "hidden": false, "defaultValue": "", "isSmartField": false, "unselectedLabel": "", "placeholder": "" } ], "default": true, "isSmartGroup": false }, { "fields": [ { "name": "adress_1", "label": "Adress 1", "type": "string", "fieldType": "text", "description": "", "groupName": "", "displayOrder": 2, "required": false, "selectedOptions": [], "options": [], "validation": { "name": "", "message": "", "data": "", "useDefaultBlockList": false }, "enabled": true, "hidden": false, "defaultValue": "", "isSmartField": false, "unselectedLabel": "", "placeholder": "" } ], "default": true, "isSmartGroup": false } ], "createdAt": 1318534279910, "updatedAt": 1413919291011, "performableHtml": "", "migratedFrom": "ld", "ignoreCurrentValues": false, "metaData": [], "deletable": true } The response from this API call are standard REST-style HTTP response codes that mark success or failure, along with the JSON representing the form that you just created. See below for a sample of this JSON output. 200 when a new form is created 401 when an unauthorized request is made 500 when an internal server error occurs Example response body on success (200 response): { "portalId": 62515, "guid": "c4c42070-c856-4a49-95cf-a02d32d05286", "name": "Docs creation test", "action": "", "method": "", "cssClass": "", "redirect": "", "submitText": "Submit", "followUpId": "", "notifyRecipients": "", "leadNurturingCampaignId": "", "formFieldGroups": [ { "fields": [ { "name": "firstname", "label": "First Name", "type": "string", "fieldType": "text", "description": "", "groupName": "", "displayOrder": 0, "required": false, "selectedOptions": [], "options": [], "validation": { "name": "", "message": "", "data": "", "useDefaultBlockList": false }, "enabled": true, "hidden": false, "defaultValue": "", "isSmartField": false, "unselectedLabel": "", "placeholder": "" } ], "default": true, "isSmartGroup": false }, { "fields": [ { "name": "lastname", "label": "Last Name", "type": "string", "fieldType": "text", "description": "", "groupName": "", "displayOrder": 1, "required": false, "selectedOptions": [], "options": [], "validation": { "name": "", "message": "", "data": "", "useDefaultBlockList": false }, "enabled": true, "hidden": false, "defaultValue": "", "isSmartField": false, "unselectedLabel": "", "placeholder": "" } ], "default": true, "isSmartGroup": false }, { "fields": [ { "name": "adress_1", "label": "Adress 1", "type": "string", "fieldType": "text", "description": "", "groupName": "", "displayOrder": 2, "required": false, "selectedOptions": [], "options": [], "validation": { "name": "", "message": "", "data": "", "useDefaultBlockList": false }, "enabled": true, "hidden": false, "defaultValue": "", "isSmartField": false, "unselectedLabel": "", "placeholder": "" } ], "default": true, "isSmartGroup": false } ], "createdAt": 1431474404764, "updatedAt": 1431474404764, "performableHtml": "", "migratedFrom": "ld", "ignoreCurrentValues": false, "metaData": [], "deletable": true }