Fields

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/signwell/main/json-schema/Fields.json",
  "title": "Fields",
  "type": "array",
  "description": "Document fields placed on a document for collecting data or signatures from recipients. At least one field must be present in the Create Document request if `draft` is `false` (unless adding a signature page by using `with_signature_page`). Field data should be sent as a 2-dimensional JSON array. One array of fields is needed for each file in the files array. An array of fields can be empty if you have a file that does not contain any fields.",
  "items": {
    "type": "array",
    "description": "Array of Fields you're adding to each file.",
    "items": {
      "type": "object",
      "properties": {
        "x": {
          "type": "number",
          "format": "float",
          "description": "Horizontal value in the coordinates of the field (in pixels). Coordinates are specific to the page where fields are located."
        },
        "y": {
          "type": "number",
          "format": "float",
          "description": "Vertical value in the coordinates of the field (in pixels). Coordinates are specific to the page where fields are located."
        },
        "page": {
          "type": "integer",
          "description": "The page number within the file. If the page does not exist within the file then the field won't be created."
        },
        "recipient_id": {
          "type": "string",
          "description": "Unique identifier of the recipient assigned to the field. Recipients assigned to fields will be the only ones that will see and be able to complete those fields."
        },
        "type": {
          "$ref": "#/components/schemas/FieldType",
          "description": "Field type of the field. Valid field types: initials, signatures, checkbox, date, and text. To autofill fields with contact data, use an autofill field type. To group checkbox fields, enter an api_id for each checkbox and add the checkbox_groups parameter."
        },
        "required": {
          "type": "boolean",
          "default": true,
          "description": "Whether the field must be completed by the recipient. Defaults to `true` except for checkbox type fields."
        },
        "label": {
          "type": "string",
          "description": "Text and Date fields only: label that is displayed when the field is empty."
        },
        "value": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "boolean"
            },
            {
              "type": "number"
            }
          ],
          "description": "Varies according to the field type. Text fields accept strings or numbers. Date fields accept Iso8601 date strings. CheckBoxes accept booleans. Signature and Initials fields can't be signed through API requests. Autofill text fields accept strings or numbers."
        },
        "api_id": {
          "type": "string",
          "description": "Unique identifier of the field. Useful when needing to reference specific field values or update a document and its fields."
        },
        "name": {
          "type": "string",
          "description": "Checkbox fields only. At least 2 checkbox fields in an array of fields must be assigned to the same recipient and grouped with selection requirements."
        },
        "validation": {
          "$ref": "#/components/schemas/TextValidation",
          "description": "Text fields only: optional validation for field values. Valid values: numbers, letters, email_address, us_phone_number, us_zip_code, us_ssn, us_age, alphanumeric, us_bank_routing_number, us_bank_account."
        },
        "fixed_width": {
          "type": "boolean",
          "default": false,
          "description": "Text fields only: whether the field width will stay fixed and text will display in multiple lines, rather than one long line. If set to `false` the field width will automatically grow horizontally to fit text on one line. Defaults to `false`."
        },
        "lock_sign_date": {
          "type": "boolean",
          "default": false,
          "description": "Date fields only: makes fields readonly and automatically populates with the date the recipient signed. Defaults to `false`."
        },
        "date_format": {
          "$ref": "#/components/schemas/DateFormat",
          "description": "Date fields only: date format to use for the field. Valid values: MM/DD/YYYY, DD/MM/YYYY, YYYY/MM/DD, Month DD, YYYY, and MM/DD/YYYY hh:mm:ss a. Defaults to MM/DD/YYYY."
        },
        "height": {
          "type": "number",
          "format": "float",
          "description": "Height of the field (in pixels). Maximum height varies by field type: Signature/Initials (200px), others (74px). When using text tags if the height is greater than the maximum height, the height will be set to the maximum height."
        },
        "width": {
          "type": "number",
          "format": "float",
          "description": "Width of the field (in pixels). For text fields, width will auto-grow unless `fixed_width` is true."
        },
        "options": {
          "type": "array",
          "description": "Array of dropdown options (for dropdown/select fields only)",
          "items": {
            "$ref": "#/components/schemas/DropdownOption"
          }
        },
        "default_option": {
          "type": "string",
          "description": "Default selected option (for dropdown/select fields only)"
        },
        "allow_other": {
          "type": "boolean",
          "description": "Whether to allow \"Other\" option with text input (for dropdown/select fields only)",
          "default": false
        }
      },
      "required": [
        "x",
        "y",
        "page",
        "recipient_id",
        "type"
      ]
    }
  }
}