Skip to main content
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>"
      }
    ]
  }
}
{
  "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

​
Authorization
string
header
required

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
​
name
string
required

Form name (required)

Example:

"Customer feedback"

​
description
string | null

Form description

Example:

"Welcome!"

​
locale
string

Form locale, e.g. en, zh-CN, it

Example:

"en"

​
timezone
string

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"

​
scene
enum<string>

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
​
layout
enum<string>

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
​
folder_token
string

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.

​
theme
object

Auto-generate a header image and matching palette from Unsplash keywords.

Response

Created with card layout

​
data
object
required
Last modified on July 9, 2026