Endpoints for creating and managing signature requests.
Create a Signature Request
Creates a new SignatureRequest, which is the primary object of the Skribble API.
A SignatureRequest defines who signs what and under which conditions. It specifies
the documents to be signed, the list of required signers, the desired signature quality
and legislation, and optional settings such as signing sequences, callback URLs, and
access control.
Compared to API v2, this version supports attaching multiple documents to a single
SignatureRequest. Additionally, the request no longer triggers invitations immediately.
Instead, the SignatureRequest is created with a status_overall of DRAFT.
If you specify an owner using the creator field, that user will find the request in
the Drafts section of their account, where they can review and complete the setup.
Once ready, call /initiate to start the SignatureRequest and send out invitations.
Create a Signature Request › Request Body
titleTitle of the signature request.
List of documents to be signed (Maximum 50).
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 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 IDSKRIBBLE_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_error_urlCallback 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 IDSKRIBBLE_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_update_urlCallback 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 IDSKRIBBLE_DOCUMENT_ID— the most recent document IDSKRIBBLE_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_start_sign_urlCallback 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 IDSKRIBBLE_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_ident_pending_urlCallback 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 IDSKRIBBLE_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_ident_error_urlCallback 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 IDSKRIBBLE_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.
customCustom field for storing application-specific data related to this signature request.
expires_atEarly 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_atmust be at most one day before the configured retention deletion date. - Only settable while
status_overall=DRAFT.
Omit or send null to leave the request without an owner-set expiry.
Create a Signature Request › Responses
Created
idtitlemessagelegislationLegislation 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:
- DRAFT The signature request has not yet been placed.
- 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.
business_idoriginauto_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 on create/update;
clear via DELETE /signature-requests/{SR_ID}/expires-at.
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_atinitiated_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.
Invite signers and start signing process
Starts the signing process for a SignatureRequest in DRAFT status.
This action sends out invitation emails and transitions status_overall
from DRAFT to OPEN. Once initiated, the SignatureRequest is no longer
visible in the Drafts section and will appear in the appropriate section
(e.g. Pending) for each participant.
path Parameters
SR_IDUnique ID received when creating the Signature Request object
Invite signers and start signing process › Responses
OK
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
idtitlemessagelegislationLegislation 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:
- DRAFT The signature request has not yet been placed.
- 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.
business_idoriginauto_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 on create/update;
clear via DELETE /signature-requests/{SR_ID}/expires-at.
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_atinitiated_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.
Delete a Signature Request
Deletes a SignatureRequest by its ID.
Important: A SignatureRequest can only be deleted via the API if:
-
the
SignatureRequesthasstatus_overall=OPEN, and -
the API user has sufficient rights on the
SignatureRequest, e.g. when it was created by the API user.
Deleting a SignatureRequest does not necessarily remove it from the
system immediately.
WITHDRAWN
When the API user is the owner of the SignatureRequest and it is
still in status_overall=OPEN, the SignatureRequest will be
WITHDRAWN.
This means the SignatureRequest will transition to
status_overall=WITHDRAWN and all pending signatures will be marked with
status_code=WITHDRAWN. Sign and read rights for all signers will be
revoked, so invited signers can no longer read or sign the
SignatureRequest.
REMOVE AS PARTICIPANT
When the API user is a participant but not the owner of the
SignatureRequest, the DELETE request will only remove the API user as a
participant.
In this case, the system will remove the SignatureRequest and its related
documents once the last remaining user deletes it via the Skribble web
application.
DELETING
When the API user is the last user with access rights to the
SignatureRequest (e.g. after a WITHDRAW), the SignatureRequest and
its related documents will be permanently removed from the system.
path Parameters
SR_IDUnique ID received when creating the Signature Request object
Delete a Signature Request › Responses
OK
Withdraw a Signature Request
Withdraws a SignatureRequest, for example when signing becomes unnecessary
or an error occurred during the invitation process. As the inviter, you can
explicitly withdraw the SignatureRequest. This removes all signers and
observers as participants and notifies them with a specified message.
Similar to deletion, the withdraw action can only be executed if:
-
The
SignatureRequesthasstatus_overall=OPEN -
The API user has sufficient rights on the
SignatureRequest, such as when it was created by the API user.
Note We recommend using the
deleteendpoint, which automatically determines the appropriate action. For example, if the API user does not have withdrawal rights, they may instead be removed as a participant, or the document may be deleted directly.Use the
withdrawendpoint specifically when you need to withdraw theSignatureRequestwhile keeping it in Skribble.
path Parameters
SR_IDUnique ID received when creating the Signature Request object
Withdraw a Signature Request › Request Body optional
messageWithdraw message.
Withdraw 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.
Add an additional document
Adds an additional document to the SignatureRequest while it is still in DRAFT status.
path Parameters
SR_IDUnique ID received when creating the Signature Request object
Add an additional document › Request Body
contentBase64 encoded bytes of the document. Maximum document size is 112.5 MB unencoded (150 MB Base64-encoded).
Add an additional document › Responses
OK
Remove a document
Deletes the document identified by DOC_ID from the SignatureRequest
with the ID SR_ID.
path Parameters
SR_IDUnique ID received when creating the Signature Request object
DOC_IDUnique ID received when creating the Document Request object
Remove a document › Responses
OK