Endpoints for handling signature requests and callbacks.
List and find Signature Requests
Returns all SignatureRequest objects that the current user has sufficient
access rights to.
Filter
You can optionally filter results using one or more of the optional parameters.
Filters search for an exact match of the corresponding field value. This
means the filter is case-sensitive and will not match partial values. For
example, account_email=john.doe@skribble.com will only match a
SignatureRequest where the account_email field is exactly
john.doe@skribble.com and will not match another.john.doe@skribble.com.
Exception: The search parameter searches for document titles that contain
the search term.
Pagination
The result set can be controlled using the optional pagination parameters
page_number and page_size, which helps prevent excessively large result
sets.
query Parameters
account_emailFilter on the field signatures[].account_email
signer_email_addressFilter on the field signatures[].signer_email_address
searchFilter on the field title to search for documents containing the serach term.
signature_statusFilter on the field signatures[].status_code with one of the valid Signature states
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.
status_overallFilter on the field status_overall with one of the valid Signature states
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_atdate has passed before all signers signed. Terminal status. - ERROR A technical error occurred. The signature request cannot be completed.
signatures_countFilter on the field signatures_count
created_byFilter on the field created_by
page_numberPage number for pagination. By default pagination is disabled.
page_sizePage size for pagination.
List and find Signature Requests › Responses
OK
List of Signature Requests.
idtitlemessagedocument_idlegislationLegislation under which the signatures are created. Required when quality is QES or AES_MINIMAL.
| Legislation | Description |
|---|---|
| ZERTES | QES according to Swiss law. This is the default. |
| EIDAS | QES according to EU law. |
qualityMinimal quality of the signatures for this signature request.
| Quality | Description |
|---|---|
| QES | Every signer must use QES. This is the default quality. Requires a legislation parameter. |
| AES | Signers will use AES if available, otherwise fall back to QES. |
| AES_MINIMAL | Signers will use QES if available, otherwise AES. At least AES is guaranteed. Requires a legislation parameter. |
| SES | Every signer uses SES. |
| DEMO | Every signer uses a DEMO signature with no legal binding. API demo users (api_demo_example_*) get this quality by default. |
| PART11 | Signers use a signature compliant with 21 CFR Part 11 regulations. |
signing_urlThe 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_overallOverall 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_atdate has passed before all signers signed. Terminal status. - ERROR A technical error occurred. The signature request cannot be completed.
businesscc_email_addressesauto_delete_atServer-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.
expires_atOwner-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.
attach_on_successWhen 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.
customCustom field for storing application-specific data related to this signature request.
ownerread_accessUsers or API keys with read access to this signature request.
write_accessUsers or API keys with write access to this signature request.
created_atupdated_atcallback_success_urlCallback URL called on overall success. See the request schema for supported placeholders and retry behaviour.
callback_error_urlCallback URL called when a signer declines or the request is withdrawn. See the request schema for supported placeholders and retry behaviour.
callback_update_urlCallback URL called on any update (e.g. one signer signed). See the request schema for supported placeholders and retry behaviour.
callback_start_sign_urlCallback URL called when a signer starts the signature process (only for xQES). See the request schema for supported placeholders and retry behaviour.
callback_ident_pending_urlCallback URL called when the identification of a signer requires manual review. See the request schema for supported placeholders and retry behaviour.
callback_ident_error_urlCallback URL called when the identification of a signer ends in an error. See the request schema for supported placeholders and retry behaviour.
Update a Signature Request
Updates an existing SignatureRequest. We recommend creating the SignatureRequest
with all necessary information upfront and using this endpoint only when changes are
required.
The following fields can be updated: title, message, legislation, quality,
signatures, cc_email_addresses, callback_success_url, callback_error_url,
callback_update_url, custom, attach_on_success, read_access, and write_access.
Updating signers
To add or remove signers, provide the complete desired state of the signatures array:
- To add a signer, include the new entry alongside all existing signers.
- To remove a signer, omit their entry from the array.
Important: Any signer not present in the
signaturesarray will be removed. Changes to signers can only be made as long as none of the signers have already completed their signature.
Updating observers
To update the observer list, provide the complete desired state of the
cc_email_addresses array. Pass null to leave the current observers unchanged.
Update a Signature Request › Request Body
idUnique ID of the signature request.
titleTitle of the signature request.
messageMessage sent to the other participants along with this signature request.
legislationLegislation under which the signatures are created. Required when quality is QES or AES_MINIMAL.
| Legislation | Description |
|---|---|
| ZERTES | QES according to Swiss law. This is the default. |
| EIDAS | QES according to EU law. |
qualityMinimal quality of the signatures for this signature request.
| Quality | Description |
|---|---|
| QES | Every signer must use QES. This is the default quality. Requires a legislation parameter. |
| AES | Signers will use AES if available, otherwise fall back to QES. |
| AES_MINIMAL | Signers will use QES if available, otherwise AES. At least AES is guaranteed. Requires a legislation parameter. |
| SES | Every signer uses SES. |
| DEMO | Every signer uses a DEMO signature with no legal binding. API demo users (api_demo_example_*) get this quality by default. |
| PART11 | Signers use a signature compliant with 21 CFR Part 11 regulations. |
callback_success_urlCallback-URL which is called on overall success.
callback_error_urlCallback-URL which is called in case of an error.
callback_update_urlCallback-URL which is called in case of an update.
callback_start_sign_urlCallback-URL which is called when a signer starts the signature process (only for xQES).
callback_ident_pending_urlCallback-URL which is called when the identification of a signer requires manual review.
callback_ident_error_urlCallback-URL which is called when the identification of a signer ends in an error.
Update a Signature Request › Responses
OK
idtitlemessagedocument_idlegislationLegislation under which the signatures are created. Required when quality is QES or AES_MINIMAL.
| Legislation | Description |
|---|---|
| ZERTES | QES according to Swiss law. This is the default. |
| EIDAS | QES according to EU law. |
qualityMinimal quality of the signatures for this signature request.
| Quality | Description |
|---|---|
| QES | Every signer must use QES. This is the default quality. Requires a legislation parameter. |
| AES | Signers will use AES if available, otherwise fall back to QES. |
| AES_MINIMAL | Signers will use QES if available, otherwise AES. At least AES is guaranteed. Requires a legislation parameter. |
| SES | Every signer uses SES. |
| DEMO | Every signer uses a DEMO signature with no legal binding. API demo users (api_demo_example_*) get this quality by default. |
| PART11 | Signers use a signature compliant with 21 CFR Part 11 regulations. |
signing_urlThe 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_overallOverall 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_atdate has passed before all signers signed. Terminal status. - ERROR A technical error occurred. The signature request cannot be completed.
businesscc_email_addressesauto_delete_atServer-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.
expires_atOwner-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.
attach_on_successWhen 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.
customCustom field for storing application-specific data related to this signature request.
ownerread_accessUsers or API keys with read access to this signature request.
write_accessUsers or API keys with write access to this signature request.
created_atupdated_atcallback_success_urlCallback URL called on overall success. See the request schema for supported placeholders and retry behaviour.
callback_error_urlCallback URL called when a signer declines or the request is withdrawn. See the request schema for supported placeholders and retry behaviour.
callback_update_urlCallback URL called on any update (e.g. one signer signed). See the request schema for supported placeholders and retry behaviour.
callback_start_sign_urlCallback URL called when a signer starts the signature process (only for xQES). See the request schema for supported placeholders and retry behaviour.
callback_ident_pending_urlCallback URL called when the identification of a signer requires manual review. See the request schema for supported placeholders and retry behaviour.
callback_ident_error_urlCallback URL called when the identification of a signer ends in an error. See the request schema for supported placeholders and retry behaviour.
List Signature Requests by bulk
Retrieves multiple SignatureRequest objects in a single call.
Provide a JSON array of SignatureRequest IDs in the request body to specify which
records to fetch. The response includes only the SignatureRequests that were
successfully found. IDs that do not match any existing record are silently ignored.
List Signature Requests by bulk › Responses
OK
List of found SignatureRequests. IDs not matching any existing record are silently ignored and absent from the response.
idtitlemessagedocument_idlegislationLegislation under which the signatures are created. Required when quality is QES or AES_MINIMAL.
| Legislation | Description |
|---|---|
| ZERTES | QES according to Swiss law. This is the default. |
| EIDAS | QES according to EU law. |
qualityMinimal quality of the signatures for this signature request.
| Quality | Description |
|---|---|
| QES | Every signer must use QES. This is the default quality. Requires a legislation parameter. |
| AES | Signers will use AES if available, otherwise fall back to QES. |
| AES_MINIMAL | Signers will use QES if available, otherwise AES. At least AES is guaranteed. Requires a legislation parameter. |
| SES | Every signer uses SES. |
| DEMO | Every signer uses a DEMO signature with no legal binding. API demo users (api_demo_example_*) get this quality by default. |
| PART11 | Signers use a signature compliant with 21 CFR Part 11 regulations. |
signing_urlThe 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_overallOverall 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_atdate has passed before all signers signed. Terminal status. - ERROR A technical error occurred. The signature request cannot be completed.
businesscc_email_addressesauto_delete_atServer-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.
expires_atOwner-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.
attach_on_successWhen 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.
customCustom field for storing application-specific data related to this signature request.
ownerread_accessUsers or API keys with read access to this signature request.
write_accessUsers or API keys with write access to this signature request.
created_atupdated_atcallback_success_urlCallback URL called on overall success. See the request schema for supported placeholders and retry behaviour.
callback_error_urlCallback URL called when a signer declines or the request is withdrawn. See the request schema for supported placeholders and retry behaviour.
callback_update_urlCallback URL called on any update (e.g. one signer signed). See the request schema for supported placeholders and retry behaviour.
callback_start_sign_urlCallback URL called when a signer starts the signature process (only for xQES). See the request schema for supported placeholders and retry behaviour.
callback_ident_pending_urlCallback URL called when the identification of a signer requires manual review. See the request schema for supported placeholders and retry behaviour.
callback_ident_error_urlCallback URL called when the identification of a signer ends in an error. See the request schema for supported placeholders and retry behaviour.
Get a Signature Request
Fetches a SignatureRequest by its ID.
path Parameters
SR_IDUnique ID received when creating the Signature Request object
Get a Signature Request › Responses
OK
idtitlemessagedocument_idlegislationLegislation under which the signatures are created. Required when quality is QES or AES_MINIMAL.
| Legislation | Description |
|---|---|
| ZERTES | QES according to Swiss law. This is the default. |
| EIDAS | QES according to EU law. |
qualityMinimal quality of the signatures for this signature request.
| Quality | Description |
|---|---|
| QES | Every signer must use QES. This is the default quality. Requires a legislation parameter. |
| AES | Signers will use AES if available, otherwise fall back to QES. |
| AES_MINIMAL | Signers will use QES if available, otherwise AES. At least AES is guaranteed. Requires a legislation parameter. |
| SES | Every signer uses SES. |
| DEMO | Every signer uses a DEMO signature with no legal binding. API demo users (api_demo_example_*) get this quality by default. |
| PART11 | Signers use a signature compliant with 21 CFR Part 11 regulations. |
signing_urlThe 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_overallOverall 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_atdate has passed before all signers signed. Terminal status. - ERROR A technical error occurred. The signature request cannot be completed.
businesscc_email_addressesauto_delete_atServer-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.
expires_atOwner-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.
attach_on_successWhen 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.
customCustom field for storing application-specific data related to this signature request.
ownerread_accessUsers or API keys with read access to this signature request.
write_accessUsers or API keys with write access to this signature request.
created_atupdated_atcallback_success_urlCallback URL called on overall success. See the request schema for supported placeholders and retry behaviour.
callback_error_urlCallback URL called when a signer declines or the request is withdrawn. See the request schema for supported placeholders and retry behaviour.
callback_update_urlCallback URL called on any update (e.g. one signer signed). See the request schema for supported placeholders and retry behaviour.
callback_start_sign_urlCallback URL called when a signer starts the signature process (only for xQES). See the request schema for supported placeholders and retry behaviour.
callback_ident_pending_urlCallback URL called when the identification of a signer requires manual review. See the request schema for supported placeholders and retry behaviour.
callback_ident_error_urlCallback URL called when the identification of a signer ends in an error. See the request schema for supported placeholders and retry behaviour.
Remind Open Signers of a Signature Request
In addition to the automatic signature reminders, manual reminders can also be initiated via the Skribble web application and also via the API.
This allows for greater flexibility in managing signature requests, ensuring that important documents are signed promptly. By using both automatic and manual reminders, you can tailor your approach to suit the specific needs of your users or customers.
Limits
There is an hourly limit on the number of signature reminders that can be sent. This limit ensures that reminders are used responsibly and prevents excessive notifications. Generally, this restriction should not affect you if you use this feature appropriately. By adhering to this limit, you can effectively manage your signature requests without overwhelming your users or customers with frequent reminders.
path Parameters
SR_IDUnique ID received when creating the Signature Request object
Remind Open Signers of a Signature Request › Responses
OK
Get Signature Request Report
Provides the signature report for a specific signature request.
By default, the report is returned as a human-readable, digitally signed
PDF document. Optionally, the report format can be changed using the
type query parameter (e.g. JSON or HTML).
The report contains all relevant information about the signature process, including signatories, timestamps, and verification details. It serves as legally valid proof of the completed signing process and can be stored or shared for auditing, compliance, or record-keeping purposes.
path Parameters
SR_IDUnique ID received when creating the Signature Request object
query Parameters
typeFormat of the Report.
Get Signature Request Report › Responses
OK
Get callback details for a signature request
Returns detailed information about the callbacks associated with a
SignatureRequest. Use this endpoint to confirm whether a callback has been
executed or to identify errors that occurred during the callback process.
Result
If no callbacks have been triggered yet, the response will be an empty
array. Otherwise, it contains an array of callback objects that have
already been executed.
path Parameters
SR_IDUnique ID received when creating the Signature Request object
Get callback details for a signature request › Responses
OK
signature_request_idSignature request's unique ID on Skribble.
typeThe type of this callback.
Possible values:
- SUCCESS Is triggered when the document has been successfully signed by all parties involved.
- UPDATE Is triggered on changes on the
SignatureRequestobject like when one person of all involved parties has signed. - ERROR Is triggered when a person declines the signature or when the
SignatureRequestis withdrawn. - START_SIGN Is triggered when a person starts the signature process (only for xQES).
- IDENT_PENDING Is triggered when the identification of a person within a signature process requires manual review.
- IDENT_ERROR Is triggered when the identification of a person within a signature process ended in an error.
stateThe state of the callback.
Possible values:
- OPEN The callback request will be executed in the next execution cycle.
- COMPLETED The callback request was executed successfully. The API received an HTTP 2xx success code in response.
- RESIGNATED The callback request has been attempted
attemptstimes but was unsuccessful. The API did not receive a valid HTTP 2xx response.
urlThe called URL of this callback.
attemptsThe attempts this callback was carried out.
messagesError messages in case that the callback failed.
created_atThe time at which the object was created.
updated_atThe time at which the object was last changed.