---
title: "Update a form title, settings, or fields"
method: PATCH
path: "/api/v1/forms/{id}"
---

# Update a form title, settings, or fields

`PATCH /api/v1/forms/{id}`

## Request

- Base URL: `https://applytovolunteer.com`
- URL: `https://applytovolunteer.com/api/v1/forms/{id}`
- Auth: HTTP bearer

Update form title, settings, or fields. Add a field by omitting its id. op add also inserts a field and must not include an id. Remove a field with op remove or removeFieldIds. New field ids are returned on added. Requires a browser session or an org API key with forms:write. A missing or wrong key is 404, not 401. An org API key shares 60 updates per organization per hour with MCP, including adds and removes. A website session is not counted. A field id that is not on the current draft is 409. A field whose key has answers or consents on any version of the form cannot be removed. A field key that already has answers or consents cannot be changed. Help text is at most 2000 characters.

## Path parameters

- `id` string, required: Form id.

## Request body

- object: JSON object. An empty object changes nothing. title must be a string when present. Added field ids are returned on added. Adding or removing fields counts toward the shared 60 updates per organization per hour.
  - `title` string: Form title, at most 200 characters. On a published form this is held as a draft until publish.
  - `settings` object: description, indexable, confirmationMessage, and notifyEmails are type-checked. Other keys are stored on the live settings object. editorSession, editorSeq, and any top-level key whose name starts with __ are ignored. The stored settings JSON is at most 32 KB.
    - `description` string, nullable: Public description. Null or an empty string clears the drafted description.
    - `indexable` boolean: Whether the published form may be indexed.
    - `confirmationMessage` string, nullable: Confirmation copy. Null or an empty string clears the drafted message.
    - `notifyEmails` string[]: Addresses notified of a new application. Replaces the live list.
  - `fields` object[]: Field rows to update, add, or remove. The value must be an array when present. At most 20 adds per call. A form can hold at most 140 fields.
    - `op` 'add' | 'update' | 'remove': add inserts a field. remove deletes it. update, or omitted with an id, patches that field. Omitted with no id inserts.
    - `id` string: Field id on the current draft. Required to update or remove. An op add row must omit id. The server assigns a new id.
    - `type` 'short_text' | 'long_text' | 'email' | 'phone' | 'number' | 'date' | 'single_select' | 'multi_select' | 'yes_no' | 'address' | 'availability_grid' | 'file' | 'signature' | 'consent': Known field type. Unknown strings are rejected.
    - `label` string: Non-blank label, at most 500 characters. Omitted labels stay as stored.
    - `helpText` string, nullable: Help text, at most 2000 characters. Null clears it.
    - `required` boolean, nullable: Whether the field is required. Null is accepted.
    - `options` string[], nullable: Choice options. Select and choice types need a non-empty list when type or options is sent. yes_no ignores stored options.
    - `stageId` string, nullable: Stage id on this form version. Null is rejected. An unknown stage id is rejected.
    - `order` integer: Zero-based order. Two fields cannot share an order.
    - `key` string: Stable field key. Blank keys are rejected.
    - `sensitive` union: false or null clears sensitivity. Otherwise one of the known sensitive kinds.
      - false
      - 'dob' | 'ssn' | 'drivers_license' | 'criminal_history' | 'abuse_cps' | 'driving_record' | 'medical' | 'minor_info' | 'financial' | 'protected_class' | 'other'
    - `consentKind` 'general_waiver' | 'background_check_authorization' | 'photo_release' | 'code_of_conduct' | 'confidentiality' | 'medical_release' | 'custom', nullable: Known consent kind, or null to clear it.
    - `consentText` string, nullable: Consent copy. Null clears it.
  - `removeFieldIds` string[]: Field ids to delete from the current draft. A field whose key has answers or consents on any version of this form is 409. A field id that is not on the draft is 409. A malformed id is 400. Combined with op remove, at most 20 deletes per call.

## Response `200`

Update form title, settings, or fields. Add a field by omitting its id. op add also inserts a field and must not include an id. Remove a field with op remove or removeFieldIds. New field ids are returned on added.

## Other responses

- `400`: The body, query, or input failed validation.
- `404`: The resource does not exist, or it is hidden from this caller. Several organization routes return 404 instead of 401 when the key is missing or the row is in another organization.
- `409`: The write conflicts with the current state.
- `429`: Too many requests from this network or organization.

---

[API](https://skmtc.dev/applytovolunteer/apis/apply2volunteer-api.md) · [All operations](https://skmtc.dev/applytovolunteer/apis/apply2volunteer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/applytovolunteer/apis/apply2volunteer-api/revisions/23df1ec8c88d?raw)