Update a form

Update basic attributes, fields, locale, timezone, layout or folder placement. All body attributes are optional; only the provided ones are updated. Theme changes (including the header_image_keywords auto-palette, which is create-only) must use PUT /forms/{token}/theme.

How the fields array is reconciled

When a fields array is provided, it replaces the form’s current field list. For each entry the server uses the optional api_code to decide intent:

• api_code omitted → add a new field; the server auto-generates an api_code (e.g. field_3).
• api_code matches an existing field → update that field in place.
• An existing field’s api_code is absent from the request → that field is removed.

The same rule applies recursively to every api_code-bearing nested object on a field (most notably choices on choice-type fields, and statements / dimensions / levels on matrix, likert and cascade): omit the api_code to add, supply it to update, and skip it to delete.

Required scope: form:write.

PUT /api/v1/forms/{token}

Update a form

cURL

curl --request PUT \
  --url https://formhug.ai/api/v1/forms/{token} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "locale": "<string>",
  "timezone": "<string>",
  "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>"
    }
  ],
  "folder_token": "<string>",
  "original_folder_token": "<string>"
}
'

200

{
  "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.

Path Parameters

token · string · required

Form token

Body

application/json

All attributes are optional; only the provided ones are updated.

name · string

New form name.

description · string | null

New form description.

locale · string

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

timezone · string

IANA timezone name used by the form when interpreting times.

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

Replaces the form's field list. See the "How the fields array is reconciled" section above for the add / update / delete semantics, and 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

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

Target folder token; empty string moves the form to the desktop (root).

original_folder_token · string

Original folder token; used for cross-folder move authorization.

Response

200

application/json

Updated

data · object · required

Show child attributes