SignatureResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/skribble/main/json-schema/skribble-signature-response-schema.json",
  "title": "SignatureResponse",
  "x-generated": "2026-10-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/skribble-sign-v2-openapi.yml#/components/schemas/SignatureResponse",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "title": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "document_id": {
      "type": "string",
      "format": "uuid"
    },
    "legislation": {
      "$ref": "#/$defs/SignatureLegislation"
    },
    "quality": {
      "$ref": "#/$defs/SignatureQuality"
    },
    "signing_url": {
      "type": "string",
      "format": "uri",
      "description": "The URL for the SignatureRequest owner to view and manage the request in the Skribble web application. This URL is not intended for signers — each signer has their own dedicated signing_url within the signatures array."
    },
    "status_overall": {
      "$ref": "#/$defs/SignatureStatusOverall"
    },
    "business": {
      "type": "string"
    },
    "signatures": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SignatureRecipientResponse"
      }
    },
    "cc_email_addresses": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "email"
      }
    },
    "auto_delete_at": {
      "type": "string",
      "format": "date",
      "description": "Server-managed date on which this signature request and its related documents are automatically\ndeleted in line with the owning business's retention policy. Not directly settable by API clients.\nMay be absent or `null` when no retention policy applies."
    },
    "expires_at": {
      "type": "string",
      "format": "date",
      "description": "Owner-set expiry date for this signature request. When this date passes, the request\ntransitions to `status_overall=EXPIRED`. Set via `expires_at` at create time.\nAbsent or `null` when no owner-set expiry has been configured."
    },
    "attachments": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SignatureAttachment"
      }
    },
    "attach_on_success": {
      "$ref": "#/$defs/AttachOnSuccess"
    },
    "custom": {
      "type": "string",
      "description": "Custom field for storing application-specific data related to this signature request."
    },
    "owner": {
      "type": "string"
    },
    "read_access": {
      "type": "array",
      "description": "Users or API keys with read access to this signature request.",
      "items": {
        "type": "string"
      }
    },
    "write_access": {
      "type": "array",
      "description": "Users or API keys with write access to this signature request.",
      "items": {
        "type": "string"
      }
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "callback_success_url": {
      "type": "string",
      "description": "Callback URL called on overall success. See the request schema for supported placeholders and retry behaviour.",
      "format": "uri"
    },
    "callback_error_url": {
      "type": "string",
      "description": "Callback URL called when a signer declines or the request is withdrawn. See the request schema for supported placeholders and retry behaviour.",
      "format": "uri"
    },
    "callback_update_url": {
      "type": "string",
      "description": "Callback URL called on any update (e.g. one signer signed). See the request schema for supported placeholders and retry behaviour.",
      "format": "uri"
    },
    "callback_start_sign_url": {
      "type": "string",
      "description": "Callback URL called when a signer starts the signature process (only for Express QES). See the request schema for supported placeholders and retry behaviour.",
      "format": "uri"
    },
    "callback_ident_pending_url": {
      "type": "string",
      "description": "Callback URL called when the identification of a signer requires manual review. See the request schema for supported placeholders and retry behaviour.",
      "format": "uri"
    },
    "callback_ident_error_url": {
      "type": "string",
      "description": "Callback URL called when the identification of a signer ends in an error. See the request schema for supported placeholders and retry behaviour.",
      "format": "uri"
    }
  },
  "$defs": {
    "AttachOnSuccess": {
      "title": "Attachment when signed",
      "type": "array",
      "description": "When a SignatureRequest has been signed by all signers, all signers and all observers are notified by email.\nSkribble provides the option to attach two types of attachments automatically to this email:\n  - the signed document and\n  - the signature protocol.\n\nThis can be configured via the business settings, which can be used to define that these documents should generally\nbe attached for all SignatureRequests created by business members.\n\nAlternatively it is possible to define the attachments on demand per SignatureRequest by using this field.",
      "items": {
        "type": "string",
        "enum": [
          "SIGNED_DOCUMENT",
          "SIGNATURE_PROTOCOL"
        ]
      }
    },
    "SignatureAttachment": {
      "title": "Signature Attachment",
      "type": "object",
      "properties": {
        "attachment_id": {
          "type": "string",
          "format": "uuid"
        },
        "filename": {
          "type": "string"
        }
      }
    },
    "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"
    },
    "SignatureLegislation": {
      "title": "Signature Legislation",
      "type": "string",
      "description": "Legislation under which the signatures are created. Required when `quality` is `QES` or `AES_MINIMAL`.\n\n| Legislation | Description |\n| --- | --- |\n| **ZERTES** | QES according to Swiss law. This is the **default**. |\n| **EIDAS** | QES according to EU law. |",
      "enum": [
        "ZERTES",
        "EIDAS"
      ]
    },
    "SignatureQuality": {
      "title": "Signature Quality",
      "type": "string",
      "description": "Minimal quality of the signatures for this signature request.\n\n| Quality | Description |\n| --- | --- |\n| **QES** | Every signer must use QES. This is the **default** quality. Requires a `legislation` parameter. |\n| **AES_MINIMAL** | Signers will use QES if available, otherwise AES. At least AES is guaranteed. Requires a `legislation` parameter. |\n| **AES** | Every signer uses AES. |\n| **SES** | Every signer uses SES. |\n| **DEMO** | Every signer uses a DEMO signature with **no legal binding**. API demo users (`api_demo_example_*`) get this quality by default. |\n| **PART11** | Signers use a signature compliant with 21 CFR Part 11 regulations. |",
      "enum": [
        "SES",
        "AES",
        "AES_MINIMAL",
        "QES",
        "DEMO",
        "PART11"
      ]
    },
    "SignatureRecipientResponse": {
      "title": "Signature Callbacks Response",
      "type": "object",
      "properties": {
        "sid": {
          "type": "string",
          "format": "uuid"
        },
        "status_code": {
          "$ref": "#/$defs/SignatureStatusCode"
        },
        "account_email": {
          "type": "string",
          "format": "email"
        },
        "signer_identity_data": {
          "$ref": "#/$defs/SignerIdentityDataResponse"
        },
        "sequence": {
          "type": "integer",
          "format": "int32"
        },
        "notify": {
          "type": "boolean",
          "description": "Whether Skribble sends notification emails to this signer. When set to `false` together with\n`signer_identity_data.identity_reference`, the TAN-based email validation for No-Account-Signers (SES) is skipped."
        },
        "signing_url": {
          "type": "string",
          "format": "uri",
          "description": "A personalized signing URL for this specific signer, distinct from the top-level signing_url of the SignatureRequest.\nIt points to the Skribble web application and will directly open the document for signing\nprovided that the user is known to Skribble and is logged in.\nOtherwise, the user must login or register first to be able to see the document.\n\nWhen the user visits this URL, they will be forwarded to a special preview page of the PDF document and can start the signature process as usual.\n\nYou can add the following query parameters to this signing_url. Skribble will respect these parameters and redirect the user to the provided URLs once the signature process is finished.\n\nExample: `https://my.skribble.com/view/4f43614a-de50-bfe1-2df3-4c881fc7840e/cd16bd0802d146fd94ff736d7d7bf551?exitURL=https%3A%2F%2Fmy-app.com%2Fsigned&redirectTimeout=10`\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `exitURL` | string (URL-encoded) | Optional URL to redirect after the signature process finished. Example: `https%3A%2F%2Fgoogle.com` |\n| `errorURL` | string (URL-encoded) | Optional URL to redirect in case of an error. Defaults to `exitURL`. Ignored if `exitURL` is not set. Example: `https%3A%2F%2Fbing.com` |\n| `declineURL` | string (URL-encoded) | Optional URL to redirect when the user declines. Defaults to `exitURL`. Ignored if `exitURL` is not set. |\n| `hidedownload` | boolean | Optional flag to hide the download button on the success screen. Requires `exitURL` to be set. Example: `true` |\n| `redirectTimeout` | integer | Optional seconds before auto-redirect after signing. Min 0 (instant), max 90. Default: 45. Example: `20` |\n| `lang` | string | Optional language code to display the signing page in a specific language. Supported values: `en` (default), `de`, `fr`. Example: `lang=fr` |\n| `overlay` | boolean | Optional flag to show or hide the Skribble overlay on the signing page. |"
        },
        "decline_message": {
          "type": "string",
          "description": "The message provided by the signer when declining the signature request. Only present if the signer declined and provided a message."
        },
        "signed_at": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp when this signer signed the document."
        },
        "signed_legislation": {
          "$ref": "#/$defs/SignatureLegislation",
          "description": "The legislation under which this signer's signature was created. Only present after signing."
        },
        "signed_quality": {
          "$ref": "#/$defs/SignatureQuality",
          "description": "The actual quality of this signer's signature. Only present after signing."
        },
        "last_viewed_at": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp when this signer last viewed the document."
        },
        "language": {
          "type": "string",
          "description": "Language preference for this signer."
        },
        "visual_signature": {
          "$ref": "#/$defs/VisualSignatureResponse"
        }
      }
    },
    "SignatureStatusCode": {
      "title": "Signature Status Code",
      "type": "string",
      "description": "The state of a signature.\n\nPossible values:\n  - **OPEN** Waiting for the user to sign a signature.\n  - **WAITING** The signer is waiting for a preceding signer in the sequence to complete.\n  - **DECLINED** The user declined to sign.\n  - **WITHDRAWN** The owner has withdrawn the signature request.\n  - **SIGNED** The user signed the document.\n  - **ERROR** A technical error occurred.",
      "enum": [
        "OPEN",
        "WAITING",
        "DECLINED",
        "WITHDRAWN",
        "SIGNED",
        "ERROR"
      ]
    },
    "SignatureStatusOverall": {
      "title": "Signature Status Overall",
      "type": "string",
      "description": "Overall signing status of the document.\n\nPossible values:\n  - **OPEN** At least one user has not signed or declined their signature yet.\n  - **DECLINED** At least one user declined to sign. The signature request failed.\n  - **WITHDRAWN** The owner has withdrawn the signature request.\n  - **SIGNED** All users signed the document. The signature request was successfully completed.\n  - **EXPIRED** The owner-set `expires_at` date has passed before all signers signed. Terminal status.\n  - **ERROR** A technical error occurred. The signature request cannot be completed.",
      "enum": [
        "OPEN",
        "DECLINED",
        "WITHDRAWN",
        "SIGNED",
        "EXPIRED",
        "ERROR"
      ]
    },
    "SignerIdentityDataResponse": {
      "title": "Signer Identity Data in Response",
      "type": "object",
      "description": "Signer identity information returned as part of the SignatureRequest response.",
      "properties": {
        "email_address": {
          "type": "string",
          "description": "Email address of the no-account-signer.",
          "format": "email"
        },
        "first_name": {
          "type": "string",
          "description": "First name of the no-account-signer."
        },
        "last_name": {
          "type": "string",
          "description": "Last name of the 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"
        },
        "identity_reference": {
          "type": "string",
          "description": "Customer-generated identifier for further identification of the signer."
        },
        "identification_require_evidence": {
          "type": "boolean",
          "description": "If set, a new identification process is started to get fresh evidence records, even if the signer is already identified."
        },
        "force_standard_qes": {
          "type": "boolean",
          "description": "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`."
        },
        "provider": {
          "type": "string",
          "description": "Evidence provider used to verify the signer's identity."
        },
        "evidence_id": {
          "type": "string",
          "description": "ID of the evidence records created during identification. Populated in the\n`SignatureRequest` response once the identification process has been completed."
        }
      }
    },
    "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."
        }
      }
    },
    "VisualSignatureResponse": {
      "title": "Visual Signature Response",
      "type": "object",
      "description": "Visual signature placement information.",
      "properties": {
        "image": {
          "$ref": "#/$defs/VisualSignatureImage"
        },
        "position": {
          "description": "Position where the signature should appear.",
          "$ref": "#/$defs/VisualSignaturePosition"
        },
        "positions": {
          "type": "array",
          "description": "List of additional positions where the signature should appear.",
          "items": {
            "$ref": "#/$defs/VisualSignaturePosition"
          }
        },
        "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. Takes precedence before positions.\n"
        },
        "text": {
          "type": "object",
          "description": "Text displayed inside the form field.",
          "properties": {
            "content": {
              "type": "string",
              "description": "Content of the text field."
            },
            "font_name": {
              "type": "string",
              "description": "Font name used. For PDF: all default PDF fonts or fonts already embedded in the document.\n"
            },
            "font_size": {
              "type": "string",
              "description": "Font size used."
            },
            "font_color": {
              "type": "string",
              "description": "Font color as RGB value encoded in hex."
            }
          }
        }
      }
    }
  }
}