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 defaults to UTC.

Required scope: form:write.

POST /api/v1/forms

Create a form

cURL

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>",
      "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>"
  }
}
'

201

{
  "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>",
        "predefined_value": "<string>",
        "placeholder": "<string>",
        "answers": [
          {
            "score": 123,
            "answer": [
              "<string>"
            ]
          }
        ],
        "answer_explanation": "<string>"
      }
    ]
  }
}

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. Defaults to UTC when omitted.

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 | Dropdown · object | Number · object | Email · object | Phone · object | Date · object | Name · object | URL · object | Address · object | Rating · object | NPS · object | Upload · 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 | 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

Dropdown

Number

Email

Phone

Date

Name

URL

Address

Rating

NPS

Upload

Cascade

Ranking

Matrix Input

Likert Scale

Time

Location

Signature

Grid Rating

Table

Product

Booking

Linked Form

Page Break

Description

Show child attributes

theme · object

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

Show child attributes

Response

201

application/json

Created with card layout

data · object · required

Show child attributes