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

idstring required

Request body

valueKeystring

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.

requiredboolean

Whether the signer must fill this field (default true)

editableboolean

When true, a prefilled value is a suggestion the signer can change before signing.

sharedFillboolean

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.

signingDateboolean

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.

labelstring

Human-readable label shown to the signer for this field

acroFieldNamestring

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.

acroOptionValuestring

For radio-group AcroForm fields: the option (export value) this field selects when checked.

optionsstring[]

Allowed values for dropdown fields. The signer picks one; fills with a value outside this list are rejected.

maxLengthnumber

Maximum characters accepted at fill time. Imported automatically from AcroForm comb fields by detection.

inputMaskstring nullable

Single-line signer input mask. Each # accepts one digit; Korala inserts every other character as a literal.

validationPatternstring

Regular expression the filled value must match (text and date fields). Rejected fills return validationMessage.

validationMessagestring

Signer-facing error when validationPattern does not match

dateFormatstring

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.

groupKeystring

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.

groupRequiredboolean

Require at least one member of this field's group to be selected before signing can complete.

requiredWhenFieldIdstring 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.

requiredWhenValuestring

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.

fontSizenumber

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.

textColorstring

Color the value is drawn in, as #rrggbb

textAlign'left' | 'center' | 'right'

Horizontal alignment of the value inside the field box

fontFamilystring

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.

multilineboolean

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.

signerIdstring required
fieldType'signature' | 'initials' | 'date' | 'text' | 'checkbox' | 'dropdown' | 'radio' required
pageNumbernumber required
xPositionnumber required
yPositionnumber required
widthnumber required
heightnumber required

Example request

{
  "required": true,
  "signingDate": true,
  "label": "Your full name",
  "acroFieldName": "topmostSubform[0].Page1[0].f1_01[0]",
  "acroOptionValue": "married",
  "options": [
    "CA",
    "NY"
  ],
  "maxLength": 11,
  "inputMask": "###-##-####",
  "validationPattern": "^\\d{3}-\\d{2}-\\d{4}$",
  "validationMessage": "Enter your SSN as XXX-XX-XXXX",
  "dateFormat": "MM-DD-YYYY",
  "groupKey": "fed_tax_class",
  "groupRequired": true,
  "requiredWhenValue": "Other",
  "fontSize": 9,
  "textColor": "#000080",
  "fontFamily": "Helvetica-Bold",
  "pageNumber": 1,
  "xPosition": 100,
  "yPosition": 200,
  "width": 200,
  "height": 50
}

Response

valueKeystring nullable

Repeated text value key, scoped to the owning signer.

idstring required
documentIdstring required
signerIdstring required
fieldType'signature' | 'initials' | 'date' | 'text' | 'checkbox' | 'dropdown' | 'radio' required
pageNumbernumber required
xPositionnumber required
yPositionnumber required
widthnumber required
heightnumber required
labelstring nullable

Human-readable label shown to the signer for this field

requiredstring required
valuestring nullable
editableboolean required

When true, a prefilled value is a suggestion the signer can change before signing.

sharedFillboolean 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.

signingDateboolean 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.

signatureImageUrlstring nullable
filledAtstring 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.

signingDateChangedAtstring 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.

acroFieldNamestring nullable

Embedded AcroForm field this field is linked to; values fill the PDF form field at completion instead of being overlay-stamped.

acroOptionValuestring nullable

For radio-group AcroForm fields: the option this field selects.

optionsstring[] nullable

Allowed values for dropdown fields

maxLengthnumber nullable

Maximum characters accepted at fill time

inputMaskstring nullable

Input mask where # represents one digit

validationPatternstring nullable

Regex the filled value must match

validationMessagestring nullable

Signer-facing error when validationPattern does not match

dateFormatstring nullable

Date fields only: format the auto-filled date is rendered in, e.g. 'MM-DD-YYYY'

groupKeystring nullable
groupRequiredboolean required

Whether at least one member of this group must be selected

requiredWhenFieldIdstring uuid nullable

Id of the field whose checked/filled state makes this field required (conditional requirement); null when unconditional

requiredWhenValuestring nullable

Exact controller value the condition triggers on; null means any checked/filled state

fontSizenumber nullable

Point size the value is drawn at, imported from the PDF form field. Null means the size is fitted to the box.

textColorstring nullable

Color the value is drawn in, as #rrggbb

textAlign'left' | 'center' | 'right'

Horizontal alignment of the value inside the field box

fontFamilystring nullable

Base font the value is drawn in, imported from the PDF form field

multilineboolean required

Whether the value may contain line breaks (a multiline form field)

createdAtstring date-time required
updatedAtstring date-time required

Example response

{
  "inputMask": "###-##-####",
  "fontSize": 9,
  "textColor": "#000080",
  "fontFamily": "Helvetica-Bold"
}

Changes

No recorded changes to this operation across all 1 revision of this API.