---
title: "Update a form field"
method: PATCH
path: "/forms/{id}/fields/{key}"
tags: ["Objects"]
---

# Update a form field

`PATCH /forms/{id}/fields/{key}`

Updates a question on a form, identified by its field `key`. Only provided properties are changed. For choice fields, `values` replaces the full list of allowed options. A field's data type cannot be changed — delete the field and add a new one to change its type.

## Path parameters

- `id` string, required
- `key` string, required

## Request body

- FormFieldUpdateInput
  - `label` string — New question label
  - `description` string, nullable — New help text under the question
  - `required` boolean — Whether an answer is required
  - `placeholder` string, nullable — New input placeholder
  - `values` string[] — Replacement list of allowed options. For SINGLE_OPTION / MULTIPLE_OPTION fields this must be non-empty; ignored for non-choice fields.
  - `settings` object — Replacement config for RATING / OPINION_SCALE fields

## Response `200`

OK

- FormFields
  - `formId` string, required — Form ID (frm_ prefix)
  - `formTitle` string, required — Form title
  - `fields` FormField[], required — Ordered list of fields on the form
    - `key` string, required — Stable field identifier. Use this as the key inside a submission `data` object when answering, and as the `key` when updating or deleting the field (e.g. cf_full_name).
    - `label` string, required — Question label shown to respondents
    - `dataType` string, required — Field data type, e.g. TEXT, LONG_TEXT, EMAIL, MOBILE, NUMBER, DATE, SINGLE_OPTION, MULTIPLE_OPTION, FILE_PICKER, SIGNATURE, CURRENCY, LINK, RATING, OPINION_SCALE.
    - `required` boolean, required — Whether an answer is required for this field
    - `type` string, required — Item kind: 'custom' for answerable questions, 'system' for built-in fields.
    - `options` FormFieldOption[], required — Allowed options. Populated for SINGLE_OPTION / MULTIPLE_OPTION fields; empty otherwise.
      - `label` string, required — Display label for the option
      - `value` string, required — Value submitted when chosen
    - `multiple` boolean, required — Whether multiple options can be selected (true for MULTIPLE_OPTION).

## Other responses

- `400` — Validation error or bad request
- `401` — Missing or invalid API key
- `403` — Insufficient permission
- `404` — Resource not found
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/heffl/apis/heffl-api-v2-beta.md) · [All operations](https://skmtc.net/heffl/apis/heffl-api-v2-beta/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/heffl/heffl-api-v2-beta/versions/27006cfef4d8/schema)