---
title: "Add a form field"
method: POST
path: "/forms/{id}/fields"
tags: ["Objects"]
---

# Add a form field

`POST /forms/{id}/fields`

Adds a question to a form (on its first page). SINGLE_OPTION / MULTIPLE_OPTION fields require a non-empty `values` list of allowed options. Returns the updated field list.

## Path parameters

- `id` string, required

## Request body

- FormFieldInput
  - `label` string, required — Question label shown to respondents
  - `dataType` 'TEXT' | 'LONG_TEXT' | 'EMAIL' | 'MOBILE' | 'NUMBER' | 'DATE' | 'SINGLE_OPTION' | 'MULTIPLE_OPTION' | 'FILE_PICKER' | 'SIGNATURE' | 'CURRENCY' | 'LINK' | 'RATING' | 'OPINION_SCALE', required — Field data type. SINGLE_OPTION / MULTIPLE_OPTION require `values`.
  - `description` string, nullable — Optional help text under the question
  - `required` boolean — Whether an answer is required. Defaults to false.
  - `placeholder` string, nullable — Optional input placeholder
  - `values` string[] — Allowed options. Required (non-empty) for SINGLE_OPTION and MULTIPLE_OPTION fields.
  - `settings` object — Extra config for RATING / OPINION_SCALE fields (e.g. { max: 5 }).

## 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/revisions/27006cfef4d8/schema)