Update a form

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

import requests

url = "https://formhug.ai/api/v1/forms/{token}"

payload = {
    "name": "<string>",
    "description": "<string>",
    "locale": "<string>",
    "timezone": "<string>",
    "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>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    locale: '<string>',
    timezone: '<string>',
    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>'
      }
    ]
  })
};

fetch('https://formhug.ai/api/v1/forms/{token}', 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/{token}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'locale' => '<string>',
    'timezone' => '<string>',
    '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>'
        ]
    ]
  ]),
  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/{token}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"timezone\": \"<string>\",\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}")

	req, _ := http.NewRequest("PUT", 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.put("https://formhug.ai/api/v1/forms/{token}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"timezone\": \"<string>\",\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}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://formhug.ai/api/v1/forms/{token}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"timezone\": \"<string>\",\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}"

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": "Form not found"
}

Forms

Update a form

Update basic attributes, fields, locale, timezone or layout. 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. To move a form between folders, use PUT /forms/{token}/folder.

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

forms

{token}

Update a form

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

import requests

url = "https://formhug.ai/api/v1/forms/{token}"

payload = {
    "name": "<string>",
    "description": "<string>",
    "locale": "<string>",
    "timezone": "<string>",
    "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>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    locale: '<string>',
    timezone: '<string>',
    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>'
      }
    ]
  })
};

fetch('https://formhug.ai/api/v1/forms/{token}', 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/{token}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'locale' => '<string>',
    'timezone' => '<string>',
    '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>'
        ]
    ]
  ]),
  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/{token}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"timezone\": \"<string>\",\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}")

	req, _ := http.NewRequest("PUT", 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.put("https://formhug.ai/api/v1/forms/{token}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"timezone\": \"<string>\",\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}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://formhug.ai/api/v1/forms/{token}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"timezone\": \"<string>\",\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}"

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": "Form not found"
}

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

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.

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

Response

Updated

data

object

required

Show child attributes

Last modified on July 24, 2026

Overview

Forms

Form Themes

Field Rules

Form Settings

Attachments

Entries

Folders

Published Forms

Published Form Entries

Participated Forms

Me

Webhooks

OAuth

Update a form

How the `fields` array is reconciled

Authorizations

Path Parameters

Body

Response