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 document 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.
Upon creation, invitations are sent to all specified signers. The response contains
the created SignatureRequest including its unique id, which is required for all
subsequent operations on this request.
Create a Signature Request › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: content, title | |
| type = object · requires: file_url, title | |
| type = object · requires: document_id, title |
contentBase64 encoded bytes of the document. Maximum document size is 112.5 MB unencoded (150 MB Base64-encoded).
titleTitle of the signature request.
content_typeContent type of bytes sent in content. Currently, only application/pdf is supported.
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. |
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_dataandaccount_emailif 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 onlysigner_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.
cc_email_addressesObserver 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_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.
Omit or send null to leave the request without an owner-set expiry.
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.
creatorSet a business member as the owner of this signature request, in addition to the API user.
write_accessUsers or API keys with write access to this signature request.
Create a Signature Request › Responses
Created
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.
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.