---
title: "Place many fields in one request"
method: POST
path: "/api/v1/documents/{id}/fields/batch"
tags: ["Documents"]
---

# Place many fields in one request

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

## Request

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

Each entry is placed either at coordinates or against text, and each is judged on its own: an entry that cannot be placed is reported with its reason while the rest are placed. The file is read once however many entries are anchored.

## Path parameters

- `id` string, required

## Request body

- AddFieldsDto
  - `fields` BatchFieldDto[], required: The fields to place, in one request. Each is placed on its own terms; one that cannot be placed does not stop the others.
    - `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: Place it at these coordinates. Give either these or anchorText, never both.
    - `xPosition` number
    - `yPosition` number
    - `anchorText` string: Place it against this text instead, as the anchored route does.
    - `occurrence` number: Which match, when the text appears more than once.
    - `position` 'replace' | 'left' | 'right' | 'above' | 'below'
    - `offsetX` number
    - `offsetY` number
    - `width` number
    - `height` number

## Response `201`

- AddFieldsResultDto
  - `placed` number, required
  - `failed` number, required
  - `results` FieldResultDto[], required
    - `index` number, required: Which entry of the request this answers.
    - `success` boolean, required
    - `field` 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
    - `error` string: Why it was not placed.

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