---
title: "Update a template field"
method: PATCH
path: "/api/v1/templates/{id}/fields/{fieldId}"
tags: ["Templates"]
---

# Update a template field

`PATCH /api/v1/templates/{id}/fields/{fieldId}`

## Request

- Base URL: `https://api.korala.ai`
- URL: `https://api.korala.ai/api/v1/templates/{id}/fields/{fieldId}`
- Auth: one of:
  - API key in header `X-API-Key`
  - `bearer` (a scheme the document does not define)

## Path parameters

- `id` string, required
- `fieldId` string, required

## Request body

- UpdateTemplateFieldDto
  - `valueKey` string: Links repeated text fields for the same signer. Signer edits or clears one occurrence to update every field with this valueKey. Independent of the merge variable used for prefills.
  - `signerRoleId` string, nullable: Signer role ID (set to null to unassign, omit to keep unchanged)
  - `placement` 'coordinate' | 'anchor' | 'bookmark'
  - `pageNumber` number: 1-based page number, or -1 for the last page.
  - `xPosition` number
  - `yPosition` number
  - `width` number
  - `height` number
  - `required` boolean
  - `mergeFieldName` string
  - `defaultValue` string
  - `editable` boolean: Treat a value resolved from variables or defaultValue as a suggestion the signer can change before signing.
  - `sharedFill` boolean: One signer role owns the generated field, but until that signer signs any signer able to act may fill or correct it. Refused on signature and initials fields.
  - `signingDate` boolean: Date fields only. True fills the field with the date the signer signs: the signing page shows today and the signer does not type it. False makes it an ordinary date the signer enters. Refused on any other type. Copied onto every document made from the template.
  - `label` string: Human-readable label shown to the signer for this field
  - `acroFieldName` string, nullable: Embedded AcroForm field to link this field to (see GET /templates/{id}/form-fields). Set to null to unlink: generated documents then draw the value at the field's coordinates instead of writing it through the PDF's form field. Omit to keep unchanged.
  - `acroOptionValue` string, nullable: For radio-group AcroForm fields: the option (export value) this field selects when checked. Set to null to clear it, omit to keep it unchanged.
  - `options` string[]: Allowed values for dropdown fields. The signer picks one; fills with a value outside this list are rejected.
  - `maxLength` number: Maximum characters accepted at fill time. Imported automatically from AcroForm comb fields by detection.
  - `inputMask` string, nullable: Single-line signer input mask. Each # accepts one digit; Korala inserts every other character as a literal.
  - `validationPattern` string: Regular expression the filled value must match (text and date fields). Rejected fills return validationMessage.
  - `validationMessage` string: Signer-facing error when validationPattern does not match
  - `dateFormat` string: Date fields only: format the auto-filled date is rendered in. Combines D/DD, M/MM, and YY/YYYY tokens with a consistent "-", "/", or "." separator. Copied onto generated document fields.
  - `fontSize` number: Point size the value is drawn at, copied onto generated document fields. Imported automatically from the base PDF's form fields; omit to fit the size to the box.
  - `textColor` string: Color the value is drawn in, as #rrggbb
  - `textAlign` 'left' | 'center' | 'right': Horizontal alignment of the value inside the field box
  - `fontFamily` string: Base font the value is drawn in, copied onto generated document fields. Imported from the base PDF's form fields; honored when the platform can render that face, otherwise the default font is used.
  - `multiline` boolean: Whether the value may contain line breaks. Imported from multiline PDF form fields and copied onto generated document fields.
  - `groupKey` string: Semantic group key. Checkbox members sharing a groupKey are mutually exclusive (checking one clears the others) even with distinct PDF fill targets — e.g. a W-9 federal tax classification.
  - `groupRequired` boolean: Require at least one member of this field's group to be selected before signing can complete.
  - `requiredWhenFieldId` string, uuid, nullable: Make this field conditionally required by the referenced template field (same template, same signer role). Set to null to clear the condition; omit to keep unchanged. Refused on choose-one group members.
  - `requiredWhenValue` string, nullable: Exact controller value the condition triggers on. Set to null to trigger on any checked/filled state; omit to keep unchanged.
  - `anchorText` string: Anchor string for anchor placement (must not contain {{ }}). Hidden markers remain in the PDF text layer — see CreateTemplateFieldDto.
  - `anchorPosition` 'replace' | 'left' | 'right' | 'above' | 'below'
  - `anchorOffsetX` number
  - `anchorOffsetY` number
  - `hideAnchor` boolean
  - `anchorMatchWholeWord` boolean
  - `bookmarkName` string: Word bookmark name for bookmark placement — see CreateTemplateFieldDto for the naming constraint.

## Response `200`

- TemplateFieldDto
  - `valueKey` string, nullable: Repeated text value key, scoped to the owning signer.
  - `id` string, required
  - `templateId` string, required
  - `signerRoleId` string, nullable
  - `fieldType` 'signature' | 'initials' | 'date' | 'text' | 'checkbox' | 'dropdown' | 'radio', required
  - `placement` 'coordinate' | 'anchor' | 'bookmark', required
  - `pageNumber` number, required: 1-based page number, or -1 for last page.
  - `xPosition` number, nullable
  - `yPosition` number, nullable
  - `width` number, required
  - `height` number, required
  - `required` boolean, required
  - `mergeFieldName` string, nullable
  - `defaultValue` string, nullable
  - `editable` boolean, required: When true, a prefilled value is a suggestion the signer can change before signing.
  - `sharedFill` boolean, required: One signer role owns the generated field, but until that signer signs any signer able to act may fill or correct it. Never true on signature or initials fields.
  - `signingDate` boolean, nullable: Date fields only. True fills the field with the date the signer signs: the signing page shows today and the signer does not type it. False makes it an ordinary date the signer enters. Refused on any other type. Null on a date made before the flag existed: a date on the signer’s own signature line is then the date of signing.
  - `label` string, nullable: Human-readable label shown to the signer for this field
  - `acroFieldName` string, nullable: Embedded AcroForm field this field is linked to; generated document fields inherit the link.
  - `acroOptionValue` string, nullable: For radio-group AcroForm fields: the option this field selects.
  - `options` string[], nullable: Allowed values for dropdown fields
  - `maxLength` number, nullable: Maximum characters accepted at fill time
  - `inputMask` string, nullable: Input mask where # represents one digit
  - `validationPattern` string, nullable: Regex the filled value must match
  - `validationMessage` string, nullable: Signer-facing error when validationPattern does not match
  - `dateFormat` string, nullable: Date fields only: format the auto-filled date is rendered in, e.g. 'MM-DD-YYYY'
  - `fontSize` number, nullable: Point size the value is drawn at, copied onto generated document fields. Null fits the size to the box.
  - `textColor` string, nullable: Color the value is drawn in, as #rrggbb
  - `textAlign` 'left' | 'center' | 'right': Horizontal alignment of the value inside the field box
  - `fontFamily` string, nullable: Base font the value is drawn in, copied onto generated document fields
  - `multiline` boolean, required: Whether the value may contain line breaks (a multiline form field)
  - `groupKey` string, nullable
  - `groupRequired` boolean, required: Whether at least one member of this group must be selected
  - `requiredWhenFieldId` string, uuid, nullable: Id of the template field whose checked/filled state makes this field required on generated documents; null when unconditional
  - `requiredWhenValue` string, nullable: Exact controller value the condition triggers on; null means any checked/filled state
  - `anchorText` string, nullable
  - `anchorPosition` 'replace' | 'left' | 'right' | 'above' | 'below', required
  - `anchorOffsetX` number, required
  - `anchorOffsetY` number, required
  - `hideAnchor` boolean, required
  - `anchorMatchWholeWord` boolean, required
  - `bookmarkName` string, nullable
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required

## Other responses

- `400`: Malformed UUID in path parameter (`id`, `fieldId`).

---

[API](https://skmtc.dev/korala/apis/korala-public-api.md) · [All operations](https://skmtc.dev/korala/apis/korala-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/korala/apis/korala-public-api/revisions/5c4d7810c507?raw)