Create a new form | Forms API

Method Details

HTTP Methods:

POST

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Headers

Products:

Marketing

For a given portal, create a new form in a given HubSpot portal. Forms are standard website forms that can be used to generate website leads.

For any form, there may be a set of fields groups with fields associated with that form in question. You can specify all of the fields that you'd like to be a part of any form that you're creating with this API call.

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

You should also note that if you attempt to create a form with the same name as one that already exists, we will return a 409, as all forms should have a unique name.

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, including 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

JSON

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 }