SignatureRecipient

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/skribble/main/json-schema/skribble-signature-recipient-schema.json",
  "title": "SignatureRecipient",
  "description": "Defines a signature recipient which can either be an individual signer or a group signer.\n\n- For individual signers, account_email and/or signer_identity_data can optionally be provided.\n- For group signers, signer_group_id must be provided and account_email/signer_identity_data must not be used.",
  "x-generated": "2026-10-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/skribble-sign-v3-openapi.yml#/components/schemas/SignatureRecipient",
  "oneOf": [
    {
      "title": "User Signer",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "sequence": {
          "type": "number",
          "description": "Optional signing order for this signer, starting at `1`. If no sequence is supplied, signers can sign in any order. When a number is set, Skribble enforces an ascending signing order across all signers, based on their `sequence` values.",
          "format": "int32",
          "default": -1
        },
        "notify": {
          "type": "boolean",
          "description": "Whether to send a notification to this signer.",
          "default": true
        },
        "document_signatures": {
          "type": "array",
          "description": "Visual signatures to place on the document.",
          "items": {
            "$ref": "#/$defs/SignatureDocument"
          }
        },
        "account_email": {
          "type": "string",
          "description": "Optional signer account email address.",
          "format": "email"
        },
        "signer_identity_data": {
          "$ref": "#/$defs/SignerIdentityData"
        }
      }
    },
    {
      "title": "Group Signer",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "signer_group_id"
      ],
      "properties": {
        "sequence": {
          "type": "number",
          "description": "Optional signing order for this signer, starting at `1`. If no sequence is supplied, signers can sign in any order. When a number is set, Skribble enforces an ascending signing order across all signers, based on their `sequence` values.",
          "format": "int32",
          "default": -1
        },
        "notify": {
          "type": "boolean",
          "description": "Whether to send a notification to this signer.",
          "default": true
        },
        "document_signatures": {
          "type": "array",
          "description": "Visual signatures to place on the document.",
          "items": {
            "$ref": "#/$defs/SignatureDocument"
          }
        },
        "signer_group_id": {
          "type": "string",
          "description": "Signer group ID."
        }
      }
    }
  ],
  "$defs": {
    "SignatureDocument": {
      "title": "Signer Document to Sign",
      "type": "object",
      "properties": {
        "document_id": {
          "type": "string",
          "description": "Unique Document ID.",
          "format": "uuid"
        },
        "visual_signature": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/VisualSignature_v3"
            }
          ]
        }
      }
    },
    "SignatureLanguage": {
      "title": "Signature Language",
      "type": "string",
      "description": "Determines in which language e-mails are sent to the user, if the user has not set their language preference yet.",
      "enum": [
        "en",
        "de",
        "fr",
        "it"
      ],
      "default": "en"
    },
    "SignerIdentityData": {
      "title": "Signer Identity Data",
      "type": "object",
      "description": "Optional (no-account) signer identity information.",
      "properties": {
        "email_address": {
          "type": "string",
          "format": "email",
          "description": "Email address of no-account-signer. Mandatory when `quality` is `SES`."
        },
        "first_name": {
          "type": "string",
          "description": "First name of no-account-signer"
        },
        "last_name": {
          "type": "string",
          "description": "Last name of no-account-signer"
        },
        "mobile_number": {
          "type": "string",
          "description": "Mobile number of the no-account-signer in E.164 format without the leading `+`:\ncountry code + area code + number, no spaces or special characters."
        },
        "language": {
          "$ref": "#/$defs/SignatureLanguage"
        },
        "provider": {
          "type": "string",
          "description": "Evidence provider where Skribble can verify the signer's identity data."
        },
        "identity_reference": {
          "type": "string",
          "description": "Optional customer-generated identifier for further identification. When set together with `notify: false`,\nthe TAN-based email validation for No-Account-Signers (SES) is skipped, allowing signers to sign directly\nwithout the Skribble TAN process."
        },
        "identification_require_evidence": {
          "type": "boolean",
          "description": "(optional) if set, even if the signer is already identified, a new identification process is started to get fresh evidence records.\nOnly supported when the signature request's quality is `QES` and Express QES is enabled for the business;\notherwise the request fails with a validation error."
        },
        "force_standard_qes": {
          "type": "boolean",
          "description": "(optional) if set to `true`, this signer is always identified via the standard QES flow and is never routed\nthrough Express QES, regardless of the business's Express QES setting or other identity flags such as\n`identification_require_evidence`."
        }
      }
    },
    "VisualSignatureImage": {
      "title": "Visual Signature Image",
      "type": "object",
      "description": "Visual signature image.",
      "required": [
        "content",
        "content_type"
      ],
      "properties": {
        "content": {
          "type": "string",
          "description": "Base64 encoded bytes of content.",
          "format": "byte"
        },
        "content_type": {
          "type": "string",
          "description": "Content type of bytes sent in content. At the moment this MUST be image/png"
        },
        "content_size": {
          "type": "integer",
          "format": "int32",
          "description": "Size of `content` in bytes. Calculated by the server.",
          "readOnly": true
        }
      }
    },
    "VisualSignaturePosition": {
      "title": "Visual Signature Position",
      "type": "object",
      "properties": {
        "page": {
          "type": "string",
          "description": "Page number (0-indexed) where the signature appears.\nThis is a String and not a number!"
        },
        "height": {
          "type": "number",
          "description": "Height of the signature in pixels."
        },
        "width": {
          "type": "number",
          "description": "Width of the signature in pixels."
        },
        "x": {
          "type": "number",
          "description": "X-coordinate (pixels from left) of signature."
        },
        "y": {
          "type": "number",
          "description": "Y-coordinate (pixels from top) of signature."
        },
        "rotation": {
          "type": "number",
          "description": "Defines a rotation of the field content. \nIf used in context with a form field, then only the values 0, 90, 180, 270 are legal.\nOtherwise every value is legal. The rotation is applied counter clockwise."
        }
      }
    },
    "VisualSignature_v3": {
      "description": "Visual signature placement information.",
      "oneOf": [
        {
          "type": "object",
          "title": "Multiple Positions",
          "description": "Use multiple explicit positions.",
          "required": [
            "positions"
          ],
          "properties": {
            "positions": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/VisualSignaturePosition"
              }
            },
            "image": {
              "$ref": "#/$defs/VisualSignatureImage"
            },
            "position": {
              "description": "Must not be provided when positions are used.",
              "readOnly": true
            },
            "form_field": {
              "description": "Must not be provided when positions are used.",
              "readOnly": true
            }
          }
        },
        {
          "type": "object",
          "title": "Form Field",
          "description": "Use a form field only.",
          "required": [
            "form_field"
          ],
          "properties": {
            "form_field": {
              "type": "string",
              "description": "Name of the form field in which the signature is placed. If multiple fields of this name are present in the document, all will be used.\n"
            },
            "image": {
              "$ref": "#/$defs/VisualSignatureImage"
            },
            "position": {
              "description": "Must not be provided when form_field is used.",
              "readOnly": true
            },
            "positions": {
              "description": "Must not be provided when form_field is used.",
              "readOnly": true
            }
          }
        }
      ]
    }
  }
}