{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/formify-eu/json-schema/formify-eu-signature-field-schema.json",
  "title": "SignatureField",
  "description": "Represents a signee who will sign the document. Each SignatureField defines one person's signature requirements, including their contact information, signature type, placement, and signing order.\n\n**Usage:**\n- Include in the `signeeDetails` array when creating a document via `POST /docs`\n- At least one SignatureField is required per document\n- Multiple SignatureFields enable multi-party signing workflows\n\n### Required vs optional fields\n\n| Field | Required? | Notes |\n|---|---|---|\n| `fullName` | **Required** | |\n| `emailAddress` | **Required unless `phoneNumber` is set** | At least one contact method must be provided |\n| `phoneNumber` | **Required unless `emailAddress` is set** | At least one contact method must be provided |\n| `phoneNumberDeliveryMethod` | Optional | Defaults to `sms` when `phoneNumber` is set |\n| `signatureType` | Optional | Defaults to `digital_ink` |\n| `signaturePlacement` | Optional | Defaults to `existing` — signature placed on an existing page. Use `new_page` to append a dedicated signature page instead. When `existing`, `signatureBox` coordinates are required |\n| `signatureBox` | Conditional | Required when `signaturePlacement` is `existing` (or omitted, since `existing` is the default) |\n| `idScanBox` | Conditional | Required when `signatureType` is `digital_ink_id_scan` |\n| `signingOrder` | Optional | Defaults to `1`. Only relevant when `enableSigningOrder` is `true` on the document |\n| `disableInvitationMessage` | Optional | Defaults to `false`. When `true`, Formify sends no signing invitation to this signee — distribute the link yourself via `GET /docs/{documentId}/recipient-links` |\n\n**Special Rules:**\n- When `signaturePlacement` is `existing`, `signatureBox.page`, `signatureBox.x`, and `signatureBox.y` are required.\n- When `signatureType` is `digital_ink_id_scan`, `signaturePlacement` must be `existing` and both `signatureBox` and `idScanBox` are required.\n\n**Common Scenarios:**\n- Single signee: One SignatureField with default settings\n- Multiple simultaneous signees: Multiple SignatureFields with same `signingOrder` value\n- Sequential signing: Multiple SignatureFields with incrementing `signingOrder` values (1, 2, 3...)",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/formify-eu-openapi.json#/components/schemas/SignatureField",
  "type": "object",
  "required": [
    "fullName"
  ],
  "properties": {
    "fullName": {
      "type": "string",
      "description": "Full name of the signee. On a document this is a real person: they are invited by name and the\nname appears on the signature.\n\nIf you do not know who will sign yet, do not put a placeholder here — use a **draft**\n(`POST /docs/drafts`, and name them before sending), a **template** (`POST /templates`, where\n`fullName` is a role label), or a **public link** (`POST /links`, which anyone can sign)."
    },
    "emailAddress": {
      "type": "string",
      "format": "email",
      "description": "Email address of the signee"
    },
    "phoneNumber": {
      "type": "string",
      "description": "The signee's phone number, formatted as an international number with a leading `+` followed by 9 to 15 digits.\n\n### Format\n- Must start with a `+`, followed by the country code and phone number.\n- Avoid spaces, dashes, or other separators.\n\nRequires `deliverySms` or `deliveryWhatsapp` capability. Check `GET /account/capabilities`.",
      "pattern": "^\\+[0-9]{9,15}$"
    },
    "phoneNumberDeliveryMethod": {
      "type": "string",
      "enum": [
        "sms",
        "whatsapp"
      ],
      "default": "sms",
      "description": "Method used to deliver messages to the provided `phoneNumber`.\n\n- `sms`: Send an SMS mobile phone message (default, requires `deliverySms` capability)\n- `whatsapp`: Send via WhatsApp (requires `deliveryWhatsapp` capability)\n\nOnly applicable when `phoneNumber` is set."
    },
    "signatureType": {
      "type": "string",
      "enum": [
        "digital_ink",
        "bankid_identification",
        "digital_ink_id_scan",
        "face_liveness"
      ],
      "default": "digital_ink",
      "description": "Type of signature / identity verification method used by the signee.\n\n- `digital_ink`: The signee draws their signature using a mouse, touchpad, or finger.\n- `bankid_identification`: The signee signs using Swedish BankID (requires `signatureBankId` capability).\n- `digital_ink_id_scan`: The signee verifies identity with an ID scan and then signs with digital ink (requires `signatureIdScan` capability).\n- `face_liveness`: The signee verifies identity using an ID scan together with a video selfie biometric liveness check (requires `signatureFaceLiveness` capability).\n\nCheck `GET /account/capabilities` to see which signature types are enabled.\n\n**Copy of the identity document.** `digital_ink_id_scan` also places an image of the front of the\nsignee's identity document in the signed document, at the `idScanBox` position. Reproducing a copy of\nan identity document requires your own legal basis: under [Terms 8.5](https://formify.eu/privacy/terms)\nyou are responsible for having one, for informing the signee of the purpose and for choosing the least\nintrusive option. Consider another signature type if you do not need a copy of the identity document\nin the document. See [PDF Form Attributes](/guides/pdf-form-attributes/) for the alternatives.\n\nOutside Sweden, `digital_ink_id_scan` and `face_liveness` require a paying account: an account on the\nFree plan gets `403 Forbidden` with `paidAccountRequired` in the error message. The same applies to SMS\nand WhatsApp invitations (a signee `phoneNumber`) and to mobile-number verification."
    },
    "signaturePlacement": {
      "type": "string",
      "enum": [
        "existing",
        "new_page"
      ],
      "default": "existing",
      "description": "Option to place the signature box on an existing page (`existing`, default) or place the field on a new signature page (A4 portrait format) at the end of the document (`new_page`).\n\n`digital_ink_id_scan` does not support `new_page` and must use `existing`, because both the signature field and the ID scan placeholder must be placed inside the document."
    },
    "signingOrder": {
      "type": "integer",
      "minimum": 1,
      "default": 1,
      "description": "Defines the order in which this signee can sign the document. Only applicable when `enableSigningOrder` is set to `true` in the document request.\n\n- **Default**: `1` (all signees can sign simultaneously)\n- **Sequential Signing**: Set different values (1, 2, 3, etc.) to enforce a signing sequence\n- **Simultaneous Signing**: Multiple signees with the same value can sign at the same time\n\nSignees will receive their invitation (email/SMS/WhatsApp) only when it's their turn to sign based on this order."
    },
    "disableInvitationMessage": {
      "type": "boolean",
      "default": false,
      "description": "When `true`, Formify sends **no signing invitation** (welcome email/SMS/WhatsApp) to this signee — neither immediately nor later when their turn comes in a signing order. The signing link is still created and the signee can still sign; you are expected to distribute the link to them yourself.\n\nRetrieve the per-recipient links to distribute via `GET /docs/{documentId}/recipient-links`. Because such links are shared outside Formify's own channels, opening one is **locked**: the recipient must first unlock it with a verification code that Formify sends to the contact method on file (see that endpoint for details).\n\nThis only suppresses the *invitation*. Reminders (`POST /docs/{documentId}/reminder`) and the completed-document email are unaffected."
    },
    "signatureBox": {
      "type": "object",
      "description": "Placement of the signature field when `signaturePlacement` is `existing`.\n\nBase size before scaling:\n- Width: 219 points\n- Height: 58 points",
      "properties": {
        "page": {
          "type": "integer",
          "description": "Page number where the signature box should be placed. The first page has index 0."
        },
        "x": {
          "type": "integer",
          "minimum": 0,
          "description": "X-coordinate for the signature box placement (minimum value 0)"
        },
        "y": {
          "type": "integer",
          "minimum": 0,
          "description": "Y-coordinate for the signature box placement (minimum value 0)"
        },
        "scale": {
          "type": "number",
          "format": "float",
          "minimum": 0.25,
          "maximum": 1.5,
          "default": 1,
          "description": "Scales the entire signature field. Applies only when `signaturePlacement` is `existing`."
        }
      }
    },
    "idScanBox": {
      "type": "object",
      "description": "Placement of the scanned ID placeholder used when `signatureType` is `digital_ink_id_scan`.\n\nThis property is required for `digital_ink_id_scan` and is not used for other signature types.\n\nThe scanned front side of the identity document is placed in the signed document at this position, so the legal basis note on `signatureType` applies.\n\nBase size before scaling:\n- Width: 218 points\n- Height: 138 points",
      "properties": {
        "page": {
          "type": "integer",
          "description": "Page number where the ID scan placeholder should be placed. The first page has index 0."
        },
        "x": {
          "type": "integer",
          "minimum": 0,
          "description": "X-coordinate for the ID scan placeholder placement (minimum value 0)"
        },
        "y": {
          "type": "integer",
          "minimum": 0,
          "description": "Y-coordinate for the ID scan placeholder placement (minimum value 0)"
        },
        "scale": {
          "type": "number",
          "format": "float",
          "minimum": 0.25,
          "maximum": 1.5,
          "default": 1,
          "description": "Scales the entire ID scan placeholder. Applies only when `signatureType` is `digital_ink_id_scan`."
        }
      }
    }
  }
}