Create a form
curl --request POST \
--url https://formhug.ai/api/v1/forms \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Customer feedback",
"description": "Welcome!",
"locale": "en",
"timezone": "America/New_York",
"folder_token": "KaB2c1",
"fields": [
{
"label": "<string>",
"type": "short_text",
"api_code": "<string>",
"cid": "<string>",
"notes": "<string>",
"private": true,
"required": true,
"customized_validation_message": "<string>",
"predefined_value": "<string>",
"placeholder": "<string>",
"answers": [
{
"score": 123,
"answer": [
"<string>"
]
}
],
"answer_explanation": "<string>"
}
],
"theme": {
"header_image_keywords": "<string>"
}
}
'import requests
url = "https://formhug.ai/api/v1/forms"
payload = {
"name": "Customer feedback",
"description": "Welcome!",
"locale": "en",
"timezone": "America/New_York",
"folder_token": "KaB2c1",
"fields": [
{
"label": "<string>",
"type": "short_text",
"api_code": "<string>",
"cid": "<string>",
"notes": "<string>",
"private": True,
"required": True,
"customized_validation_message": "<string>",
"predefined_value": "<string>",
"placeholder": "<string>",
"answers": [
{
"score": 123,
"answer": ["<string>"]
}
],
"answer_explanation": "<string>"
}
],
"theme": { "header_image_keywords": "<string>" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Customer feedback',
description: 'Welcome!',
locale: 'en',
timezone: 'America/New_York',
folder_token: 'KaB2c1',
fields: [
{
label: '<string>',
type: 'short_text',
api_code: '<string>',
cid: '<string>',
notes: '<string>',
private: true,
required: true,
customized_validation_message: '<string>',
predefined_value: '<string>',
placeholder: '<string>',
answers: [{score: 123, answer: ['<string>']}],
answer_explanation: '<string>'
}
],
theme: {header_image_keywords: '<string>'}
})
};
fetch('https://formhug.ai/api/v1/forms', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://formhug.ai/api/v1/forms",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Customer feedback',
'description' => 'Welcome!',
'locale' => 'en',
'timezone' => 'America/New_York',
'folder_token' => 'KaB2c1',
'fields' => [
[
'label' => '<string>',
'type' => 'short_text',
'api_code' => '<string>',
'cid' => '<string>',
'notes' => '<string>',
'private' => true,
'required' => true,
'customized_validation_message' => '<string>',
'predefined_value' => '<string>',
'placeholder' => '<string>',
'answers' => [
[
'score' => 123,
'answer' => [
'<string>'
]
]
],
'answer_explanation' => '<string>'
]
],
'theme' => [
'header_image_keywords' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://formhug.ai/api/v1/forms"
payload := strings.NewReader("{\n \"name\": \"Customer feedback\",\n \"description\": \"Welcome!\",\n \"locale\": \"en\",\n \"timezone\": \"America/New_York\",\n \"folder_token\": \"KaB2c1\",\n \"fields\": [\n {\n \"label\": \"<string>\",\n \"type\": \"short_text\",\n \"api_code\": \"<string>\",\n \"cid\": \"<string>\",\n \"notes\": \"<string>\",\n \"private\": true,\n \"required\": true,\n \"customized_validation_message\": \"<string>\",\n \"predefined_value\": \"<string>\",\n \"placeholder\": \"<string>\",\n \"answers\": [\n {\n \"score\": 123,\n \"answer\": [\n \"<string>\"\n ]\n }\n ],\n \"answer_explanation\": \"<string>\"\n }\n ],\n \"theme\": {\n \"header_image_keywords\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://formhug.ai/api/v1/forms")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Customer feedback\",\n \"description\": \"Welcome!\",\n \"locale\": \"en\",\n \"timezone\": \"America/New_York\",\n \"folder_token\": \"KaB2c1\",\n \"fields\": [\n {\n \"label\": \"<string>\",\n \"type\": \"short_text\",\n \"api_code\": \"<string>\",\n \"cid\": \"<string>\",\n \"notes\": \"<string>\",\n \"private\": true,\n \"required\": true,\n \"customized_validation_message\": \"<string>\",\n \"predefined_value\": \"<string>\",\n \"placeholder\": \"<string>\",\n \"answers\": [\n {\n \"score\": 123,\n \"answer\": [\n \"<string>\"\n ]\n }\n ],\n \"answer_explanation\": \"<string>\"\n }\n ],\n \"theme\": {\n \"header_image_keywords\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://formhug.ai/api/v1/forms")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Customer feedback\",\n \"description\": \"Welcome!\",\n \"locale\": \"en\",\n \"timezone\": \"America/New_York\",\n \"folder_token\": \"KaB2c1\",\n \"fields\": [\n {\n \"label\": \"<string>\",\n \"type\": \"short_text\",\n \"api_code\": \"<string>\",\n \"cid\": \"<string>\",\n \"notes\": \"<string>\",\n \"private\": true,\n \"required\": true,\n \"customized_validation_message\": \"<string>\",\n \"predefined_value\": \"<string>\",\n \"placeholder\": \"<string>\",\n \"answers\": [\n {\n \"score\": 123,\n \"answer\": [\n \"<string>\"\n ]\n }\n ],\n \"answer_explanation\": \"<string>\"\n }\n ],\n \"theme\": {\n \"header_image_keywords\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"name": "Customer feedback",
"description": "Please share your feedback",
"token": "Wabc12",
"scene": "survey",
"layout": "classic",
"locale": "en",
"timezone": "UTC",
"created_at": "2026-05-12T08:00:00Z",
"updated_at": "2026-05-12T09:00:00Z",
"last_entry_created_at": "2026-05-13T10:00:00Z",
"entries_count": 42,
"folder": {
"token": "KaB2c1",
"name": "Work"
},
"fields": [
{
"type": "short_text",
"label": "Name",
"api_code": "field_1",
"notes": "Please use your real name",
"private": false,
"required": true,
"customized_validation_message": "<string>",
"cid": "<string>",
"predefined_value": "<string>",
"placeholder": "<string>",
"answers": [
{
"score": 123,
"answer": [
"<string>"
]
}
],
"answer_explanation": "<string>"
}
],
"owned": true,
"role": "manager"
}
}{
"error": "Forbidden"
}{
"error": "Target folder not found"
}{
"error": "Invalid field input",
"error_details": [
{
"attribute": "name",
"message": "object at root is missing required properties: name"
}
]
}Forms
Create a form
Create a blank form. Optionally supply initial fields, locale, timezone and a theme
(via header_image_keywords for Unsplash-based header image). When timezone is omitted, the
form uses your account’s timezone, falling back to UTC if that is unset or invalid.
Required scope: form:write.
POST
/
api
/
v1
/
forms
Create a form
curl --request POST \
--url https://formhug.ai/api/v1/forms \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Customer feedback",
"description": "Welcome!",
"locale": "en",
"timezone": "America/New_York",
"folder_token": "KaB2c1",
"fields": [
{
"label": "<string>",
"type": "short_text",
"api_code": "<string>",
"cid": "<string>",
"notes": "<string>",
"private": true,
"required": true,
"customized_validation_message": "<string>",
"predefined_value": "<string>",
"placeholder": "<string>",
"answers": [
{
"score": 123,
"answer": [
"<string>"
]
}
],
"answer_explanation": "<string>"
}
],
"theme": {
"header_image_keywords": "<string>"
}
}
'import requests
url = "https://formhug.ai/api/v1/forms"
payload = {
"name": "Customer feedback",
"description": "Welcome!",
"locale": "en",
"timezone": "America/New_York",
"folder_token": "KaB2c1",
"fields": [
{
"label": "<string>",
"type": "short_text",
"api_code": "<string>",
"cid": "<string>",
"notes": "<string>",
"private": True,
"required": True,
"customized_validation_message": "<string>",
"predefined_value": "<string>",
"placeholder": "<string>",
"answers": [
{
"score": 123,
"answer": ["<string>"]
}
],
"answer_explanation": "<string>"
}
],
"theme": { "header_image_keywords": "<string>" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Customer feedback',
description: 'Welcome!',
locale: 'en',
timezone: 'America/New_York',
folder_token: 'KaB2c1',
fields: [
{
label: '<string>',
type: 'short_text',
api_code: '<string>',
cid: '<string>',
notes: '<string>',
private: true,
required: true,
customized_validation_message: '<string>',
predefined_value: '<string>',
placeholder: '<string>',
answers: [{score: 123, answer: ['<string>']}],
answer_explanation: '<string>'
}
],
theme: {header_image_keywords: '<string>'}
})
};
fetch('https://formhug.ai/api/v1/forms', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://formhug.ai/api/v1/forms",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Customer feedback',
'description' => 'Welcome!',
'locale' => 'en',
'timezone' => 'America/New_York',
'folder_token' => 'KaB2c1',
'fields' => [
[
'label' => '<string>',
'type' => 'short_text',
'api_code' => '<string>',
'cid' => '<string>',
'notes' => '<string>',
'private' => true,
'required' => true,
'customized_validation_message' => '<string>',
'predefined_value' => '<string>',
'placeholder' => '<string>',
'answers' => [
[
'score' => 123,
'answer' => [
'<string>'
]
]
],
'answer_explanation' => '<string>'
]
],
'theme' => [
'header_image_keywords' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://formhug.ai/api/v1/forms"
payload := strings.NewReader("{\n \"name\": \"Customer feedback\",\n \"description\": \"Welcome!\",\n \"locale\": \"en\",\n \"timezone\": \"America/New_York\",\n \"folder_token\": \"KaB2c1\",\n \"fields\": [\n {\n \"label\": \"<string>\",\n \"type\": \"short_text\",\n \"api_code\": \"<string>\",\n \"cid\": \"<string>\",\n \"notes\": \"<string>\",\n \"private\": true,\n \"required\": true,\n \"customized_validation_message\": \"<string>\",\n \"predefined_value\": \"<string>\",\n \"placeholder\": \"<string>\",\n \"answers\": [\n {\n \"score\": 123,\n \"answer\": [\n \"<string>\"\n ]\n }\n ],\n \"answer_explanation\": \"<string>\"\n }\n ],\n \"theme\": {\n \"header_image_keywords\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://formhug.ai/api/v1/forms")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Customer feedback\",\n \"description\": \"Welcome!\",\n \"locale\": \"en\",\n \"timezone\": \"America/New_York\",\n \"folder_token\": \"KaB2c1\",\n \"fields\": [\n {\n \"label\": \"<string>\",\n \"type\": \"short_text\",\n \"api_code\": \"<string>\",\n \"cid\": \"<string>\",\n \"notes\": \"<string>\",\n \"private\": true,\n \"required\": true,\n \"customized_validation_message\": \"<string>\",\n \"predefined_value\": \"<string>\",\n \"placeholder\": \"<string>\",\n \"answers\": [\n {\n \"score\": 123,\n \"answer\": [\n \"<string>\"\n ]\n }\n ],\n \"answer_explanation\": \"<string>\"\n }\n ],\n \"theme\": {\n \"header_image_keywords\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://formhug.ai/api/v1/forms")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Customer feedback\",\n \"description\": \"Welcome!\",\n \"locale\": \"en\",\n \"timezone\": \"America/New_York\",\n \"folder_token\": \"KaB2c1\",\n \"fields\": [\n {\n \"label\": \"<string>\",\n \"type\": \"short_text\",\n \"api_code\": \"<string>\",\n \"cid\": \"<string>\",\n \"notes\": \"<string>\",\n \"private\": true,\n \"required\": true,\n \"customized_validation_message\": \"<string>\",\n \"predefined_value\": \"<string>\",\n \"placeholder\": \"<string>\",\n \"answers\": [\n {\n \"score\": 123,\n \"answer\": [\n \"<string>\"\n ]\n }\n ],\n \"answer_explanation\": \"<string>\"\n }\n ],\n \"theme\": {\n \"header_image_keywords\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"name": "Customer feedback",
"description": "Please share your feedback",
"token": "Wabc12",
"scene": "survey",
"layout": "classic",
"locale": "en",
"timezone": "UTC",
"created_at": "2026-05-12T08:00:00Z",
"updated_at": "2026-05-12T09:00:00Z",
"last_entry_created_at": "2026-05-13T10:00:00Z",
"entries_count": 42,
"folder": {
"token": "KaB2c1",
"name": "Work"
},
"fields": [
{
"type": "short_text",
"label": "Name",
"api_code": "field_1",
"notes": "Please use your real name",
"private": false,
"required": true,
"customized_validation_message": "<string>",
"cid": "<string>",
"predefined_value": "<string>",
"placeholder": "<string>",
"answers": [
{
"score": 123,
"answer": [
"<string>"
]
}
],
"answer_explanation": "<string>"
}
],
"owned": true,
"role": "manager"
}
}{
"error": "Forbidden"
}{
"error": "Target folder not found"
}{
"error": "Invalid field input",
"error_details": [
{
"attribute": "name",
"message": "object at root is missing required properties: name"
}
]
}Authorizations
Personal Access Token prefixed with fh_. Sent as Authorization: Bearer fh_xxx.
The scope required by each endpoint is listed in that endpoint's description.
Body
application/json
Form name (required)
Example:
"Customer feedback"
Form description
Example:
"Welcome!"
Form locale, e.g. en, zh-CN, it
Example:
"en"
IANA timezone name used by the form when interpreting times. When omitted, defaults to your account's timezone, falling back to UTC if that is unset or invalid.
Example:
"America/New_York"
Form scene. Currently restricted to exam and evaluation on V1 create;
omit for the default survey scene. When set, scorable field types may
carry top-level answers / answer_explanation keys — see the relevant
field-type input schemas.
Available options:
exam, evaluation Form layout. classic (default) supports a solid wallpaper color; card additionally supports a wallpaper background image. Switching layout recomputes the theme palette (dominant color + label/choice/header text colors).
Available options:
classic, card Create the form inside this folder
Example:
"KaB2c1"
fields
(Short Text · object | Long Text · object | Radio · object | Checkbox · object | Image Radio · object | Image Checkbox · object | Dropdown · object | Number · object | Email · object | Phone · object | Date · object | Name · object | URL · object | Address · object | Rating · object | NPS · object | Upload · object | Audio · object | Cascade · object | Ranking · object | Matrix Input · object | Likert Scale · object | Time · object | Location · object | Signature · object | Grid Rating · object | Table · object | Product · object | Booking · object | Linked Form · object | Formula · object | Page Break · object | Description · object)[]
Initial field definitions. Each entry may optionally carry an api_code to pre-seed the identifier (and similarly for nested objects such as choices). See the Form Field schema for the parameters accepted per field type.
A field definition supplied on form create / update. Every field accepts the shared keys
(label, api_code, notes, private, required, ...) plus a set of type-specific keys
determined by its type — see the per-type sections below.
- Short Text
- Long Text
- Radio
- Checkbox
- Image Radio
- Image Checkbox
- Dropdown
- Number
- Email
- Phone
- Date
- Name
- URL
- Address
- Rating
- NPS
- Upload
- Audio
- Cascade
- Ranking
- Matrix Input
- Likert Scale
- Time
- Location
- Signature
- Grid Rating
- Table
- Product
- Booking
- Linked Form
- Formula
- Page Break
- Description
Show child attributes
Show child attributes
Auto-generate a header image and matching palette from Unsplash keywords.
Show child attributes
Show child attributes
Response
Created with card layout
Show child attributes
Show child attributes
Last modified on July 24, 2026
Was this page helpful?
⌘I