Skribble API v2 (2.1.0)

To use the Skribble API, you first need an API key and an API user. Both can be managed on the API key page in your business profile. Consult our guide for setup instructions.

Skribble offers two types of API keys:

Demo API keys

Demo API keys are for testing and development purposes. Signatures created with demo keys have no legal weight and are free of charge.

Demo keys can be identified by their name, which starts with api_demo.

Production API keys

Production API keys are used for live systems. Signatures created with production keys will be invoiced.

Production keys can be identified by their name, which starts with api_production or, in some cases, api_prod.

⚠ Note All costs incurred by signature requests created with your API keys will be charged to your business. We recommend starting with a demo API key during development and testing, and switching to a production key only once testing is complete.

For help setting up Skribble Business, contact us at info@skribble.com.

To obtain an access token, authenticate using the /access/login endpoint. You can pass your credentials as raw JSON or as x-www-form-urlencoded key-value pairs (see example requests).

Upon successful authentication, a JSON Web Token (JWT) is returned. This JWT must be included in nearly every API request.

The access token is passed in the Authorization HTTP header using the Bearer scheme. Example: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI...

Token life cycle

API key

API keys have a long but finite lifetime. The validity period depends on the volume of API calls and is agreed upon individually as part of the shared secret agreement.

Access token

Access tokens have a lifetime of approximately 20 minutes. Automatic token renewal is not currently supported.

Logout

There is no logout endpoint. Access tokens expire automatically after the defined lifetime.

Upload using a Base64 encoded file as content.

Returns an array of all accessible Document objects.

Fetches the metadata for the Document identified by its ID.

Deletes a Document by its ID. Deletion behaves similarly to deleting a SignatureRequest and does not necessarily remove the object from the system immediately.

If more than one participant is involved, the DELETE request only removes the current user from the Document.

The system permanently removes the Document once the last user deletes it via the Skribble web application.

Downloads the content of the document identified by its ID. Returns either a PDF binary or a JSON object containing a Base64-encoded PDF.

Returns a preview image for a specific page of the uploaded PDF document. Page numbering starts at 0 for the first page.

Use the optional scale parameter to control the preview size: scale=100 returns a full-size preview, while scale=20 returns a thumbnail.

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.

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 signatures array 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.

Fetches a SignatureRequest by its ID.

Deletes a SignatureRequest by its ID.

Important: A SignatureRequest can only be deleted via the API if:

1. the SignatureRequest has status_overall=OPEN, and

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

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 SignatureRequest has status_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 delete endpoint, 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 withdraw endpoint specifically when you need to withdraw the SignatureRequest while keeping it in Skribble.

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.

To add an individual signer, use the same parameters as when creating a SignatureRequest. The process is the same. By using account_email, you can add a signer who has a Skribble account. By using signer_identity_data, you can invite a No-Account-Signer to the SignatureRequest with the ID {{SR_ID}}.

💡 Good to know

We recommend this approach of combining signer_idendity_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 an existing Skribble account. Instead, they will have to access the document using the specific link provided in their signature invitation email.

Removes an individual signer from the SignatureRequest. Provide the SignatureRequest ID SR_ID and the Signature ID SID of the signer to remove.

Use this endpoint to provide supplementary documents (for example, Terms & Conditions or appendices) to participants of a SignatureRequest.

Attachments are delivered to participants together with the SignatureRequest.

Content type limits: The Skribble API accepts PDF files, image files, Microsoft Office files, and plain text files.

Allowed content 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

Content size limits: The maximum size of a single attachment is approximately 40 MB. The maximum request size is 60 MB.

Amount limits: There is currently no limit on the number of attachments per SignatureRequest. Abuse of this service may result in enforced limits.

Downloads the content of the attachment identified by ATTACHMENT_ID for the SignatureRequest with the ID SR_ID.

Deletes the attachment identified by ATTACHMENT_ID from the SignatureRequest with the ID SR_ID.

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.

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.

Fetches a SignatureRequest by its ID.

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.

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.

Uploads a document and affixes an electronic seal in a single call.

Optionally, a visual signature can also be placed on the document.

The response contains the document_id of the newly created sealed document, which can be used to retrieve it.

Starts the signing process by uploading the PDF document content and assigning it a title.

Limited lifetime

Send-To objects and their related Documents and SignatureRequests are only guaranteed for a limited lifetime.

• A Send-To request that is not claimed by a user — i.e. where a user does not add the document to their list of documents to sign — is deleted automatically after one day.

• All Send-To objects and their related Documents and SignatureRequest objects, regardless of status, are deleted automatically after 90 days.

To call the track endpoint, you must include the value of the access_code field—received when creating the Send-To object—in the request header X-Accesscode.

To call the download endpoint, you must include the value of the access_code field—received when creating the Send-To object—in the request header X-Accesscode.

The response contains the originally provided PDF document in its current state, which may be signed, declined, withdrawn, or still open for signing. The current status can be retrieved using the track endpoint.