Schemas

The username of the users credentials to login

The API key of the users credentials to login

URI identifying the problem category. The host of this URI depends on the environment the request was made against (e.g. api.skribble.com and api.skribble.de for the production regions; other environments use their respective hosts). Match on the path segment after /problem/ rather than the full URI. Known values:

• https://api.skribble.com/problem/problem-with-message — generic error with a message
• https://api.skribble.com/problem/entity-not-found — requested resource does not exist
• https://api.skribble.com/problem/feature-not-enabled — a required feature is not enabled for the business
• https://api.skribble.com/problem/constraint-violation — request violates a domain constraint
• https://api.skribble.com/problem/parameterized — parameterized error with details
• https://api.skribble.com/problem/limit-exceeded — a usage limit was exceeded

HTTP method of the failing request.

Request URI of the failing request.

HTTP status code, mirroring the response status line.

Human-readable error message.

Optional machine-readable error key. Present for a subset of errors that carry a stable code. Prefer matching on this field over parsing message, which is not part of the stable contract.

Known keys, grouped by category:

Authentication (403):

• error.auth.token_expired: the access token has expired
• error.auth.token_invalid: the access token is malformed or otherwise invalid
• error.auth.credentials_invalid: the supplied credentials were rejected

Rate limiting (429):

• error.rate_limit.exceeded: a generic rate limit was exceeded
• error.rate_limit.reminder: the per-signature-request reminder limit was exceeded

File upload / attachment (400):

• file.attachment.unsupported: the uploaded attachment type is not supported
• file.malware.detected: malware was detected in the uploaded file

PDF processing (400):

• file.pdf.general_error: the PDF could not be loaded (corrupt or unreadable)
• file.pdf.encryption.unknown_password: the PDF is encrypted with an unknown password
• file.pdf.encryption.no_changes_allowed: the PDF's signature permissions (DocMDP) do not allow the required changes
• file.pdf.encryption.unknown_permissions: the PDF is encrypted with an unknown permissions type
• file.pdf.signature_verification.failed: verification of an existing PDF signature failed

Signature request (400):

• error.sr.last_document_cannot_be_removed: the request would remove the only remaining document from the signature request; an SR must keep at least one document

Email address of the no-account-signer.

First name of the no-account-signer.

Last name of the no-account-signer.

Mobile number of the no-account-signer.

Determines in which language e-mails are sent to the user, if the user has not set their language preference yet.

Customer-generated identifier for further identification of the signer.

If set, a new identification process is started to get fresh evidence records, even if the signer is already identified. If the business hasn't enabled Express QES, the request is rejected.

Evidence provider used to verify the signer's identity.

ID of the evidence records created during identification. Populated in the SignatureRequest response once the identification process has been completed.

Base64 encoded bytes of content.

Content type of bytes sent in content. At the moment this MUST be image/png

Size of content in bytes. Calculated by the server.

Page number (0-indexed) where the signature appears. This is a String and not a number!

Height of the signature in pixels.

Width of the signature in pixels.

X-coordinate (pixels from left) of signature.

Y-coordinate (pixels from top) of signature.

Defines a rotation of the field content. If used in context with a form field, then only the values 0, 90, 180, 270 are legal. Otherwise every value is legal. The rotation is applied counter clockwise.

Visual signature image.

Position where the signature should appear.

List of additional positions where the signature should appear.

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.

Text displayed inside the form field.

The state of a signature.

Possible values:

• OPEN Waiting for the user to sign a signature.
• WAITING The signer is waiting for a preceding signer in the sequence to complete.
• DECLINED The user declined to sign.
• WITHDRAWN The owner has withdrawn the signature request.
• SIGNED The user signed the document.
• ERROR A technical error occurred.

Signer identity information returned as part of the SignatureRequest response.

Whether Skribble sends notification emails to this signer. When set to false together with signer_identity_data.identity_reference, the TAN-based email validation for No-Account-Signers (SES) is skipped.

A personalized signing URL for this specific signer, distinct from the top-level signing_url of the SignatureRequest. It points to the Skribble web application and will directly open the document for signing provided that the user is known to Skribble and is logged in. Otherwise, the user must login or register first to be able to see the document.

When 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.

You 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.

Example: https://my.skribble.com/view/4f43614a-de50-bfe1-2df3-4c881fc7840e/cd16bd0802d146fd94ff736d7d7bf551?exitURL=https%3A%2F%2Fmy-app.com%2Fsigned&redirectTimeout=10

The message provided by the signer when declining the signature request. Only present if the signer declined and provided a message.

Timestamp when this signer signed the document.

The legislation under which this signer's signature was created. Only present after signing.

The actual quality of this signer's signature. Only present after signing.

Timestamp when this signer last viewed the document.

Language preference for this signer.

Visual signature placement information.

When a SignatureRequest has been signed by all signers, all signers and all observers are notified by email. Skribble provides the option to attach two types of attachments automatically to this email:

• the signed document and
• the signature protocol.

This can be configured via the business settings, which can be used to define that these documents should generally be attached for all SignatureRequests created by business members.

Alternatively it is possible to define the attachments on demand per SignatureRequest by using this field.

Legislation under which the signatures are created. Required when quality is QES or AES_MINIMAL.

Minimal quality of the signatures for this signature request.

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.

Overall signing status of the document.

Possible values:

• OPEN At least one user has not signed or declined their signature yet.
• DECLINED At least one user declined to sign. The signature request failed.
• WITHDRAWN The owner has withdrawn the signature request.
• SIGNED All users signed the document. The signature request was successfully completed.
• EXPIRED The owner-set expires_at date has passed before all signers signed. Terminal status.
• ERROR A technical error occurred. The signature request cannot be completed.

Server-managed date on which this signature request and its related documents are automatically deleted in line with the owning business's retention policy. Not directly settable by API clients. May be absent or null when no retention policy applies.

Owner-set expiry date for this signature request. When this date passes, the request transitions to status_overall=EXPIRED. Set via expires_at at create time. Absent or null when no owner-set expiry has been configured.

When a SignatureRequest has been signed by all signers, all signers and all observers are notified by email. Skribble provides the option to attach two types of attachments automatically to this email:

• the signed document and
• the signature protocol.

This can be configured via the business settings, which can be used to define that these documents should generally be attached for all SignatureRequests created by business members.

Alternatively it is possible to define the attachments on demand per SignatureRequest by using this field.

Custom field for storing application-specific data related to this signature request.

Users or API keys with read access to this signature request.

Users or API keys with write access to this signature request.

Callback URL called on overall success. See the request schema for supported placeholders and retry behaviour.

Callback URL called when a signer declines or the request is withdrawn. See the request schema for supported placeholders and retry behaviour.

Callback URL called on any update (e.g. one signer signed). See the request schema for supported placeholders and retry behaviour.

Callback URL called when a signer starts the signature process (only for xQES). See the request schema for supported placeholders and retry behaviour.

Callback URL called when the identification of a signer requires manual review. See the request schema for supported placeholders and retry behaviour.

Callback URL called when the identification of a signer ends in an error. See the request schema for supported placeholders and retry behaviour.

Email address of no-account-signer. Mandatory when quality is SES.

First name of no-account-signer

Last name of no-account-signer

Mobile number of no-account-signer

Determines in which language e-mails are sent to the user, if the user has not set their language preference yet.

Evidence provider where Skribble can verify the signer's identity data.

Optional customer-generated identifier for further identification. When set together with notify: false, the TAN-based email validation for No-Account-Signers (SES) is skipped, allowing signers to sign directly without the Skribble TAN process.

(optional) if set, even if the signer is already identified, a new identification process is started to get fresh evidence records. If the business hasn't enabled Express QES, the request is rejected.

Optional signer account email address.

Optional signer sequence.

Whether to send a notification to this signer.

Determines in which language e-mails are sent to the user, if the user has not set their language preference yet.

Optional (no-account) signer identity information.

Visual signature placement information.

Unique ID of the signature request.

Title of the signature request.

Message sent to the other participants along with this signature request.

Legislation under which the signatures are created. Required when quality is QES or AES_MINIMAL.

Minimal quality of the signatures for this signature request.

Callback-URL which is called on overall success.

Callback-URL which is called in case of an error.

Callback-URL which is called in case of an update.

Callback-URL which is called when a signer starts the signature process (only for xQES).

Callback-URL which is called when the identification of a signer requires manual review.

Callback-URL which is called when the identification of a signer ends in an error.

Title of the signature request.

Message sent to the other participants along with this signature request.

Legislation under which the signatures are created. Required when quality is QES or AES_MINIMAL.

Minimal quality of the signatures for this signature request.

List of recipients required to sign the document.

It is possible to create a SignatureRequest where one or more invited participants won't need a Skribble account to sign the SignatureRequest. Those signers are called No-Account-Signers (NAS).

To invite a No-Account-Signer (NAS), include an entry in the signatures array without an account_email and provide the signer's details using signer_identity_data instead.

Each entry in the signatures array will be treated as a distinct identity. This means two entries with the same signer_identity_data are treated as two different identities and require that this person signs the document twice.

Optionally you can combine signer_identity_data and account_email in your requests. In this case, the system checks first if there is a Skribble account with the specified e-mail address. If one is found the existing Skribble user will be invited to sign the document. Otherwise, the specified user in signer_identity_data will be invited to sign.

Good to know We recommend combining signer_identity_data and account_email if you are unsure whether the user has a Skribble account. The benefit is that an existing Skribble user will afterwards find the SignatureRequest in the "To sign" section of their account on my.skribble.com. Conversely, if you invite them using only signer_identity_data, the document will not appear in their Skribble account, even if they have one. Instead, they will have to access the document using the specific link provided in their signature invitation email.

Missing fields like first name and last name can easily be adjusted by the signer through the Skribble web client.

Observer email addresses of users who are granted read access and to whom notifications are sent. Any email address is accepted, regardless of whether the recipient already has a Skribble account. If the observer does not yet have an account, they will need to create one to access the document.

Callback URL called via POST when all signers have signed (overall success).

The URL supports the following placeholders, replaced with current SignatureRequest data before each call:

• SKRIBBLE_SIGNATURE_REQUEST_ID — the SignatureRequest ID
• SKRIBBLE_DOCUMENT_ID — the final signed document ID

Retry: If the endpoint is unreachable, Skribble retries every 10 minutes for up to 2 hours. The endpoint can return a Retry-After header (seconds) to control the retry interval.

Callback URL called via POST when a signer declines or the SignatureRequest is withdrawn.

The URL supports the following placeholders, replaced with current SignatureRequest data before each call:

• SKRIBBLE_SIGNATURE_REQUEST_ID — the SignatureRequest ID
• SKRIBBLE_DOCUMENT_ID — the most recent document ID

Retry: If the endpoint is unreachable, Skribble retries every 10 minutes for up to 2 hours. The endpoint can return a Retry-After header (seconds) to control the retry interval.

Callback URL called via POST on any change to the SignatureRequest (e.g. one signer has signed).

The URL supports the following placeholders, replaced with current SignatureRequest data before each call:

• SKRIBBLE_SIGNATURE_REQUEST_ID — the SignatureRequest ID
• SKRIBBLE_DOCUMENT_ID — the most recent document ID
• SKRIBBLE_SIGNATURE_ID — the Signature ID (SID) of the signature just made

Retry: If the endpoint is unreachable, Skribble retries every 10 minutes for up to 2 hours. The endpoint can return a Retry-After header (seconds) to control the retry interval.

Callback URL called via POST when a signer starts the signature process (only for xQES).

The URL supports the following placeholders, replaced with current SignatureRequest data before each call:

• SKRIBBLE_SIGNATURE_REQUEST_ID — the SignatureRequest ID
• SKRIBBLE_DOCUMENT_ID — the most recent document ID

Retry: If the endpoint is unreachable, Skribble retries every 10 minutes for up to 2 hours. The endpoint can return a Retry-After header (seconds) to control the retry interval.

Callback URL called via POST when the identification of a signer requires manual review.

The URL supports the following placeholders, replaced with current SignatureRequest data before each call:

• SKRIBBLE_SIGNATURE_REQUEST_ID — the SignatureRequest ID
• SKRIBBLE_DOCUMENT_ID — the most recent document ID

Retry: If the endpoint is unreachable, Skribble retries every 10 minutes for up to 2 hours. The endpoint can return a Retry-After header (seconds) to control the retry interval.

Callback URL called via POST when the identification of a signer ends in an error.

The URL supports the following placeholders, replaced with current SignatureRequest data before each call:

• SKRIBBLE_SIGNATURE_REQUEST_ID — the SignatureRequest ID
• SKRIBBLE_DOCUMENT_ID — the most recent document ID

Retry: If the endpoint is unreachable, Skribble retries every 10 minutes for up to 2 hours. The endpoint can return a Retry-After header (seconds) to control the retry interval.

Custom field for storing application-specific data related to this signature request.

Early access. This field is available to opted-in businesses only. To request access, contact support@skribble.com.

Setting expires_at requires the signature-request expiry feature to be enabled for the business. If it is not, the request fails with 403 Forbidden (problem type feature-not-enabled).

Owner-set expiry date for this signature request (ISO 8601 date, e.g. 2026-12-31).

When set, the SignatureRequest transitions to status_overall=EXPIRED at the end of the given day if it has not been completed. EXPIRED is a terminal status.

Constraints

• Must be today or later.
• Must be at most 6 months in the future.
• If the owning business has a retention policy configured, expires_at must be at most one day before the configured retention deletion date.

Omit or send null to leave the request without an owner-set expiry.

When a SignatureRequest has been signed by all signers, all signers and all observers are notified by email. Skribble provides the option to attach two types of attachments automatically to this email:

• the signed document and
• the signature protocol.

This can be configured via the business settings, which can be used to define that these documents should generally be attached for all SignatureRequests created by business members.

Alternatively it is possible to define the attachments on demand per SignatureRequest by using this field.

Set a business member as the owner of this signature request, in addition to the API user.

Users or API keys with write access to this signature request.

Withdraw message.

Metadata and status information about the signature request

List of users involved in the signature process

File name of the attachment.

Content type of the attachment. Supported types: application/pdf, application/x-tika-msoffice, application/x-tika-ooxml, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.ms-word.document.macroEnabled.12, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel.sheet.macroenabled.12, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation, application/vnd.ms-powerpoint.presentation.macroEnabled.12, image/gif, image/jpeg, image/png, text/plain

Base64 encoded bytes of the attachment.

Internal ID of the evidence record.

Unique transaction code for the identification process.

Internal account ID associated with the identification.

Internal workflow ID used for the identification process.

Current status of the identification process.

Present if the identification is pending manual review, otherwise null.

Timestamp when the identification was created.

Timestamp when the identification evidence expires.

Timestamp when the identification process was started by the signer.

Timestamp when the identification process was completed. Null if not yet completed.

Timestamp when the identification was reviewed. Null if not reviewed.

Base64 encoded bytes of the document.

Account name of the seal contract that should be used. If your company own more than one seal and the field account_name is not given or empty, then the first given seal for the API user will be used for sealing.

Title of the document.

Generated document ID

Page number (0-indexed) where the field appears. This is a String and not a number!

Height of the field in pixels.

Width of the field in pixels.

X-coordinate (pixels from left) of field.

Y-coordinate (pixels from top) of field.

Defines a rotation of the field content. If used in context with a form field, then only the values 0, 90, 180, 270 are legal. Otherwise every value is legal. The rotation is applied counter clockwise.

Signature Formfield name

Signature status of Formfield

List of positions where the Formfield is present

ID of the previous version of the Document object. As documents are immutable, every change will create a new version, which is connected by the parent_id.

Optional detected Signature Formfields

Users or API keys with read access to this document.

Users or API keys with write access to this document.

Title of the document.

Give specific users or API keys read access to this document.

Give specific users or API keys write access to this document.

Base64 encoded bytes of the document.

Title of the document.

Base64 Encoded Document.

URL to claim document to get signed.

Generated send-to document ID

Access code to be used in for endpoints.

Status of the Send-To request

User who claimed the Send-To request

List of signers for the Send-To request

Best possible quality, but AES at a minimum.

Action performed on the signature request

ID of the related signature request

Optional cost center

Minimal quality of the signatures for this signature request.

Legislation under which the signatures are created. Required when quality is QES or AES_MINIMAL.