FormField

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/formify-eu/json-schema/formify-eu-form-field-schema.json",
  "title": "FormField",
  "description": "Represents an interactive form field embedded in a PDF document. FormFields are extracted from PDF forms and can be read or updated via the API.\n\n**Usage:**\n- Retrieve form fields from uploaded files: `GET /files/{fileId}/fields`\n- Retrieve form fields from documents: `GET /docs/{documentId}/fields`\n- Get field values from completed documents: `GET /docs/{documentId}/field-values`\n- Update field values: `POST /docs/{documentId}/field-values`\n\n**Field Types:**\n- **textField**: Single-line or multi-line text input\n- **checkbox**: Boolean selection (checked/unchecked)\n- **radioButton**: Single selection from a group of options\n- **combobox**: Dropdown with editable text input\n- **listbox**: List selection (single or multiple)\n\n**Common Use Cases:**\n- Pre-fill contract templates with customer data\n- Collect structured information from signees\n- Create dynamic forms with conditional logic\n- Extract data from completed forms for processing\n\n**Key Properties:**\n- `name`: Unique identifier for the field (use this when updating values)\n- `required`: Whether the field must be filled before signing\n- `editable`: Whether the field can be updated via API\n- `readOnly`: Whether signees can modify the field\n- `value` / `defaultValues`: The field's predefined starting values, not what anyone has entered\n\n**Definitions, not entered values.** These endpoints describe the fields a document contains: their names,\ntypes, positions and predefined values. What a recipient has actually filled in is a separate thing, read\nwith `GET /docs/{documentId}/field-values` once the document is completed.",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/formify-eu-openapi.json#/components/schemas/FormField",
  "type": "object",
  "properties": {
    "fieldId": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier for the field."
    },
    "name": {
      "type": "string",
      "description": "The name of the form field, used as the key for API interactions."
    },
    "label": {
      "type": "string",
      "description": "The display label of the form field."
    },
    "type": {
      "type": "string",
      "enum": [
        "checkbox",
        "combobox",
        "listbox",
        "radioButton",
        "textField"
      ],
      "description": "The type of the form field."
    },
    "value": {
      "type": [
        "string",
        "null"
      ],
      "description": "The field's predefined starting value — what it was built with, not what anyone has since filled in.\nIt is the first entry of `defaultValues`, and is `null` when the field has no predefined value.\n\nTo read what has actually been entered, use `GET /docs/{documentId}/field-values` on a completed\ndocument. Entered values are stored per recipient and are never returned by this endpoint."
    },
    "defaultValues": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "description": "List of default values for the form field."
    },
    "options": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "The display label of the option."
          },
          "value": {
            "type": "string",
            "description": "The value associated with the option."
          }
        }
      },
      "description": "List of available options for dropdown or choice fields."
    },
    "required": {
      "type": "boolean",
      "description": "Indicates if the field is mandatory for submission."
    },
    "readOnly": {
      "type": "boolean",
      "description": "Indicates if the field is read-only and cannot be modified."
    },
    "editable": {
      "type": "boolean",
      "description": "Indicates if the field is editable through the `POST /docs/{documentId}/field-values` endpoint."
    },
    "multiLine": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Indicates if the field supports multi-line text."
    },
    "comb": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Indicates if the field uses comb formatting for text input."
    },
    "page": {
      "type": "integer",
      "description": "The page index (zero-based) where the field is located."
    },
    "boundingBox": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "x": {
          "type": "number",
          "description": "The X coordinate of the field's top-left corner."
        },
        "y": {
          "type": "number",
          "description": "The Y coordinate of the field's top-left corner."
        },
        "width": {
          "type": "number",
          "description": "The width of the field in points."
        },
        "height": {
          "type": "number",
          "description": "The height of the field in points."
        }
      },
      "description": "The bounding box of the field on the page."
    }
  }
}