---
title: "Add a signature field to the document"
method: POST
path: "/api/v1/documents/{id}/fields"
tags: ["Documents"]
---

# Add a signature field to the document

`POST /api/v1/documents/{id}/fields`

## Request

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

## Path parameters

- `id` string, required

## Request body

- AddFieldDto
  - `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.
  - `required` boolean: Whether the signer must fill this field (default true)
  - `editable` boolean: When true, a prefilled value is a suggestion the signer can change before signing.
  - `sharedFill` boolean: One signer owns the field, but until they sign any signer able to act may fill or correct it — the employer preparing a part the employee confirms. 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.
  - `label` string: Human-readable label shown to the signer for this field
  - `acroFieldName` string: Fully-qualified name of an embedded AcroForm field in the PDF (see GET /documents/{id}/form-fields). When set, the value is written through the PDF form field at completion — comb boxes, checkboxes, and length limits render natively — instead of being overlay-stamped at the coordinates.
  - `acroOptionValue` string: For radio-group AcroForm fields: the option (export value) this field selects when checked.
  - `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. Without it, a format hint in the label (e.g. "Date (MM-DD-YYYY)") applies, then the signer locale.
  - `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: Make this field conditionally required: it must be filled before signing only while the referenced field (same document, same signer) is checked/filled — e.g. a W-9 LLC tax-classification code required only when the LLC box is checked. Refused on choose-one group members.
  - `requiredWhenValue` string: Narrow the condition to an exact value of the referenced field (e.g. a dropdown's "Other" choice). Omit to trigger on any checked/filled state.
  - `fontSize` number: Point size the value is drawn at. Imported automatically from the PDF form field's default appearance; 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. Imported from the PDF form field; honored when the platform can render that face, otherwise the default font is used. Values written through the form field render in the form's own font regardless.
  - `multiline` boolean: Whether the value may contain line breaks. Imported from multiline PDF form fields: the signer gets a multi-line editor and the value is laid out from the top of the box, wrapping to its width.
  - `signerId` string, required
  - `fieldType` 'signature' | 'initials' | 'date' | 'text' | 'checkbox' | 'dropdown' | 'radio', required
  - `pageNumber` number, required
  - `xPosition` number, required
  - `yPosition` number, required
  - `width` number, required
  - `height` number, required

## Response `201`

- FieldDto
  - `valueKey` string, nullable: Repeated text value key, scoped to the owning signer.
  - `id` string, required
  - `documentId` string, required
  - `signerId` string, required
  - `fieldType` 'signature' | 'initials' | 'date' | 'text' | 'checkbox' | 'dropdown' | 'radio', required
  - `pageNumber` number, required
  - `xPosition` number, required
  - `yPosition` number, required
  - `width` number, required
  - `height` number, required
  - `label` string, nullable: Human-readable label shown to the signer for this field
  - `required` string, required
  - `value` string, nullable
  - `editable` boolean, required: When true, a prefilled value is a suggestion the signer can change before signing.
  - `sharedFill` boolean, required: One signer owns the field, but until they sign any signer able to act may fill or correct it — the employer preparing a part the employee confirms. 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.
  - `signatureImageUrl` string, nullable
  - `filledAt` string, date-time, nullable
  - `filledBy` 'sender' | 'signer': Who wrote the current value: the sender (a non-editable template prefill or a signing-packet lock) or the signer (any fill, including bulk signing on their behalf). Null while unfilled.
  - `signingDateChangedAt` string, date-time, nullable: When the signer changed the date beside their signature from the automatic date of signing to one of their own. Null otherwise.
  - `acroFieldName` string, nullable: Embedded AcroForm field this field is linked to; values fill the PDF form field at completion instead of being overlay-stamped.
  - `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'
  - `groupKey` string, nullable
  - `groupRequired` boolean, required: Whether at least one member of this group must be selected
  - `requiredWhenFieldId` string, uuid, nullable: Id of the field whose checked/filled state makes this field required (conditional requirement); null when unconditional
  - `requiredWhenValue` string, nullable: Exact controller value the condition triggers on; null means any checked/filled state
  - `fontSize` number, nullable: Point size the value is drawn at, imported from the PDF form field. Null means the size is fitted 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, imported from the PDF form field
  - `multiline` boolean, required: Whether the value may contain line breaks (a multiline form field)
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required

## Other responses

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

---

[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)