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>",
      "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_url": "<string>",
    "header_image_keywords": "<string>"
  }
}
'
{
  "data": {
    "name": "Customer feedback",
    "description": "Please share your feedback",
    "token": "Wabc12",
    "scene": "survey",
    "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>"
      }
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://formhug.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

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
​
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)[]

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. Provide either header_image_url or header_image_keywords.

Response

Created

​
data
object
required
Last modified on May 21, 2026