UpdateDraftRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/formify-eu/json-schema/formify-eu-update-draft-request-schema.json",
  "title": "UpdateDraftRequest",
  "description": "`templateId` is **not** accepted here, and sending it is refused with a `400` rather than silently\nignored — a draft cannot be re-based on a template, because the copied fields and the layer they live\non belong to the document it already has. To start from a different template, create a new draft.\n\n`fileId` **is** accepted: supply a different one to replace the draft's document, or omit it to keep\nthe current one.",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/formify-eu-openapi.json#/components/schemas/UpdateDraftRequest",
  "type": "object",
  "properties": {
    "fileId": {
      "type": "string",
      "format": "uuid",
      "description": "File ID from `POST /files`. If omitted, the draft keeps its current file."
    },
    "name": {
      "type": "string",
      "description": "Name of the draft"
    },
    "signeeDetails": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/DraftSignatureField"
      },
      "description": "List of signees. Replaces existing signees entirely. Contact methods and placement coordinates are optional during the draft phase."
    },
    "enableSigningOrder": {
      "type": "boolean",
      "default": false,
      "description": "Enable sequential signing order. Requires `signingOrder` capability."
    },
    "language": {
      "type": "string",
      "enum": [
        "en",
        "sv",
        "es"
      ],
      "default": "en",
      "description": "Language of the document"
    },
    "sharingSetting": {
      "type": "string",
      "enum": [
        "private",
        "shared"
      ],
      "description": "Sharing setting"
    },
    "userId": {
      "type": "string",
      "format": "uuid",
      "description": "Assign ownership to a different user within the same account"
    },
    "personalMessage": {
      "type": "string",
      "maxLength": 500,
      "description": "Message included in invitations when the draft is sent. Max 500 characters."
    },
    "aiAssistant": {
      "$ref": "#/$defs/AiAssistant"
    },
    "errorLanguage": {
      "type": "string",
      "enum": [
        "en",
        "sv",
        "es"
      ],
      "description": "Language for error messages"
    }
  },
  "$defs": {
    "AiAssistant": {
      "type": "object",
      "description": "Configuration for the optional AI Assistant shown to signees while reviewing and signing a document.\n\n**Usage:**\n- Set `enabled` to `true` to activate the assistant for the document.\n- Set `textToSpeech` to `true` if the assistant should be able to read its responses aloud.\n- Use `language` to control the assistant language.\n\n**Defaults:**\n- `enabled`: `false` \n- `textToSpeech`: `false` \n- `language`: `en` \n\n**Processing:**\nWhen the AI Assistant is enabled, the document will be created with `status: \"processing\"` and `documentUrl` will be `null`. The document will be finalized asynchronously, and invitations to signees will be sent once processing is complete.\n\n> **Availability:** Requires the `aiAssistant` capability. Check `GET /account/capabilities`.",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": false,
          "description": "Enables the AI Assistant for the document."
        },
        "textToSpeech": {
          "type": "boolean",
          "default": false,
          "description": "Enables text-to-speech so the assistant can read its responses aloud."
        },
        "language": {
          "type": "string",
          "enum": [
            "ar",
            "bg",
            "zh",
            "hr",
            "cs",
            "da",
            "nl",
            "en",
            "fil",
            "fi",
            "fr",
            "de",
            "el",
            "hi",
            "id",
            "it",
            "ja",
            "ko",
            "ms",
            "pl",
            "pt",
            "ro",
            "ru",
            "es",
            "sv",
            "ta",
            "tr",
            "uk"
          ],
          "default": "en",
          "description": "Language used by the AI Assistant. Supports 28 languages."
        }
      }
    },
    "DraftSignatureField": {
      "type": "object",
      "description": "Represents a signee in a draft document. This schema shares the same properties as `SignatureField` but with no required fields — all properties are optional during the draft phase.\n\n**Draft-specific behavior:**\n- **All fields are optional** when creating or updating a draft (but just as for regular document signature requests, the required fields must be entered before sending the draft).\n- `fullName` may be a **placeholder or role** — `\"Buyer\"`, `\"Landlord\"` — while you do not yet know who will sign. Replace it with the real name before sending; whatever is there when the draft is sent is the name the signee sees.\n- Contact methods (`emailAddress`, `phoneNumber`) are only validated when the draft is sent via `POST /docs/drafts/{draftId}/send`.\n- `signatureBox` coordinates can be omitted or incomplete — they are only validated at send time.\n- `idScanBox` coordinates for `digital_ink_id_scan` can also be omitted until the draft is sent.\n\nWhen the draft is sent, all the same validations as `POST /docs` apply (`fullName` required, at least one contact method, valid coordinates, etc.).",
      "properties": {
        "fullName": {
          "type": "string",
          "description": "Name of the signee. While the document is still a draft this may be a **placeholder or role**\n— `\"Buyer\"`, `\"Landlord\"` — for a signee you have not decided on yet.\n\nWhatever is here when the draft is sent is the name that signee is invited under and that appears\non the signature, so replace it with the real name first."
        },
        "emailAddress": {
          "type": "string",
          "format": "email",
          "description": "Email address of the signee. Optional during draft phase; required when sending the draft (unless `phoneNumber` is set)."
        },
        "phoneNumber": {
          "type": "string",
          "description": "The signee's phone number, formatted as an international number with a leading `+` followed by 9 to 15 digits. Optional during draft phase; required when sending the draft (unless `emailAddress` is set).\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` on the draft.\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"
        },
        "disableInvitationMessage": {
          "type": "boolean",
          "default": false,
          "description": "When `true`, Formify sends **no signing invitation** (welcome email/SMS/WhatsApp) to this signee when the draft is sent — neither immediately nor later when their turn comes in a signing order. The signing link is still created; you distribute it yourself via `GET /docs/{documentId}/recipient-links` once the draft has been sent.\n\nSuch self-distributed links are verification-locked on open (a code is sent to the contact on file). Only the invitation is suppressed — reminders and the completed-document email are unaffected."
        },
        "signatureBox": {
          "type": "object",
          "description": "Placement of the signature field when `signaturePlacement` is `existing`. Optional during draft phase; validated when the draft is sent.\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`. Optional during draft phase; validated when the draft is sent.\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`."
            }
          }
        }
      }
    }
  }
}