The Skribble API v2 documentation describes the public available Skribble API version 2.
\nOur API allows businesses and teams of any size to fully integrate the e-signing solution of Skribble with any internal systems, software or SaaS solution.
\nOur goal is to provide a simple API that enables integrators to create signature requests programmatically. A signature request is a description of who is going to sign what, and needs to be created in order to perform an electronic signature on a document. Signature request is the primary object of the API.
\nThe signature request enables the integrator to describe a short document flow between the participants in a signing process.
\nThe actual signing of a PDF document by a signatory always takes place inside the Skribble web application.
\nTo get started with the Skribble API, you will need to set up Skribble Business. To learn more, see the chapter Setting up Skribble Business in the Skribble Admin Guide.
\nFor feedback and questions, please use our Google Group public-api-users@skribble.com
\nIf you are looking for Skribble API v1 documentation please visit https://api-v1-doc.skribble.com
\nWith the release of Skribble API v2, we will continue to support Skribble API v1 until 30.11.2025. After this date, Skribble API v1 will remain functional; however, we will no longer guarantee that changes will not break the existing Skribble API v1.
\nWe recommend upgrading to Skribble API v2 to take advantage of additional features and to keep up with the latest developments in Skribble. Upgrading will ensure that you can take advantage of new features, enhancements and improvements that are part of our ongoing development work.
\nData Hosting Regions:
\nThe Skribble web application is available in different hosting regions.
\nPlease ensure you use the appropriate base URL for your Skribble accountโs hosting region:
\nGermany and the EU:
\nWeb application: https://my.skribble.de
\nAPI v2 base URL: https://api.skribble.de/v2
\nSwitzerland and the Rest of the World:
\nWeb application: https://my.skribble.com
\nAPI v2 base URL: https://api.skribble.com/v2
\nMake sure to use the correct base URL based on your account's hosting region!
\nThe Skribble API v2 was officially released at 25.06.2024
\nThe Skribble API v2 is the latest version of our API.
\nSkribble API v2 maintains backward compatibility with Skribble API v1. This ensures that objects such as SignatureRequests, created using either version of the API, can be seamlessly read and processed by the other version within their respective contexts. If you encounter any compatibility issues or have specific concerns, please inform us so that we can address them promptly.
However, we receommend you to upgrade to Skribble API v2. Upgrading to Skribble API v2 not only preserves compatibility but also offers enhanced functionalities and optimizations, ensuring a smoother experience and access to the latest features.
\nFor integration
\nSend-ToFor SignatureRequests
\nCreate
\nAdd and remove single signers from a SignatureRequest
Define a specific SignatureRequest owner
Define a signing sequence
\nDefine multiple visual signatures per signature
\nDisable TAN based NAS notifications for SES
\nWithdraw a SignatureRequest
Find
\nEnhanced search capabilities with title search for SignatureRequest
Extended SignatureRequest listing with pagination options
Triggers
\nFor users
\nFor monitoring
\nSignatureRequest callbacksFor reporting
\nTo successfully migrate from Skribble API v1 to API v2, please follow these steps:
\nUpdate Base URL:
\nhttps://api.skribble.com/v1 to https://api.skribble.com/v2.Field Renaming:
\nIn SignatureRequest-related requests, rename the field signer_email_address to account_email.
Expect the field account_email instead of signer_email_address in the corresponding responses.
For detailed information, refer to the chapter: Reference > SignatureRequests > ObjectDetails.
\nVisual Signature Positioning:
\nChange from using the visual_signature.position object to the visual_signature.positions array of position objects.
This change accommodates the ability to define multiple visual signatures per signer, with Skribble now utilizing a positions array instead of a single position.
For more details, see the chapter: Reference > SignatureRequests > Create > Basic Actions > Define Visual Signatures.
\nBy following these migration tasks, you can ensure a smooth transition to API v2 and take full advantage of its new features and improvements.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Versions","slug":"versions"}],"owner":"6930652","collectionId":"6a168fd0-2b99-4f46-8d43-9ac0b1e00d0b","publishedId":"2sA3XV7K6V","public":true,"customColor":{"top-bar":"263B65","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2024-06-25T06:50:59.000Z"},"item":[{"name":"๐ Authentication","item":[{"name":"Login as user \"api_demo_your_name\"","event":[{"listen":"test","script":{"exec":["// Tests for login request","pm.test(pm.info.requestName + \" - Response has HTTP STATUS 200\", function () {"," pm.response.to.have.status(200);","});","","pm.test(pm.info.requestName + \" - Response has token\", function () {"," pm.response.to.be.ok;"," pm.response.to.have.body();","});","","let responseToken = pm.response.text();","pm.environment.set(\"AUTH_ACCESS_TOKEN\", responseToken );",""],"type":"text/javascript","id":"0b01d37d-446c-4ec0-9c91-aa13f760c9eb"}},{"listen":"prerequest","script":{"exec":["// First of all: empty dynamic variables","pm.collectionVariables.set(\"AUTH_ACCESS_TOKEN\",\"\");"],"type":"text/javascript","id":"0afac63a-9b0e-4571-ab14-01835cfd0811"}}],"id":"4faa3dbc-6b67-450c-a592-d93add26d56a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"username\": \"add_your_api_name_here\",\r\n \"api-key\": \"please_enter_your_password_here\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/access/login","description":"To obtain an access token, log in using the /access/login resource.
You can pass your login data using raw JSON or alternatively as x-www-form-urlencoded key:value pairs(see example requests).
Upon a successful login, a JSON Web Token (JWT) will be returned (see ).
The JWT MUST be included in nearly every request made to the API.
The access token is transported in an HTTP header called Authorization.
The content of the header starts with Bearer followed by the JWT string.
Example: Authorization: {{vault:bearer-token}}
The API key has a long, but not an unlimited lifetime.
\nThe validity period should depend on the volume of API calls and will be discussed individually for each customer as part of the shared secret agreement.
\nThe access token has a lifetime of about 20 minutes.
Currently, we do not renew the access token automatically. But this is planned for future releases.
There is no logout. The access token will expire after the defined time.
\n","urlObject":{"protocol":"https","path":["v2","access","login"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[{"id":"af38ebfc-12c8-4fdf-828d-0a47eacb1e46","name":"Alternative login as user \"api_demo_your_name\" - x-www-form-urlencoded (200)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/x-www-form-urlencoded","name":"Content-Type","type":"text"}],"body":{"mode":"urlencoded","urlencoded":[{"key":"username","value":"add_your_api_name_here","type":"text"},{"key":"api-key","value":"please_enter_your_password_here","type":"text"}],"options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/access/login"},"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJWlMxY0pXQXlXVFdZeDR6dXRGNzJlYWVILTA0MUprTDF5N2Z3aXA1T3UwIn0Ei3Hm3rhjOAq5dWo6Z0l6bzvyGCXd87oRoOWDM2sW4KErCKYmcQ6ks8FVj3Fn8wXNIVAnp5ClZvWNw9Uks1zM9P2IXBbBPn7DIQGvM ..."},{"id":"6b512596-f02b-4f38-9ce3-972eef05ef64","name":"Login user api_demo_user_name (200)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","name":"Content-Type","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"username\": \"add_your_api_name_here\",\r\n \"api-key\": \"please_enter_your_password_here\",\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/access/login"},"status":"OK","code":200,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJWlMxY0pXQXlXVFdZeDR6dXRGNzJlYWVILTA0MUprTDF5N2Z3aXA1T3UwIn0Ei3Hm3rhjOAq5dWo6Z0l6bzvyGCXd87oRoOWDM2sW4KErCKYmcQ6ks8FVj3Fn8wXNIVAnp5ClZvWNw9Uks1zM9P2IXBbBPn7DIQGvM ..."},{"id":"9591e0b1-f4cb-4324-8be3-e0cdac8a00df","name":"Login user api_demo_user_name (400)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","name":"Content-Type","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"username\": \"add_your_api_name_here\",\r\n \"api-key\": \"wrong_api_key\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/access/login"},"status":"Bad request","code":400,"_postman_previewlanguage":"plain","header":[],"cookie":[],"responseTime":null,"body":"Please ensure your username and api-key are correct!"}],"_postman_id":"4faa3dbc-6b67-450c-a592-d93add26d56a"}],"id":"d0385a4a-edea-4498-9f49-dde78c28cf50","description":"In order to use the API of Skribble, you first need to obtain an API key with an API user. Both can be accessed inside the API key page inside your business profile. From here, you can create and manage your API keys. Consult our guide for help.
\nSkribble offers two types of API keys:
\nDemo API keys
Demo API keys are for testing and development purposes.
You can recognize these keys by their name, which start with api_demo.
Signatures requested by such keys don't have any legal weight and are free of charge.
Production API keys
Production API keys are used for live systems.
Signatures requested by such keys will be invoiced.
You can recognize these keys by their name, which usually starts with api_production or in some rare cases just with api_prod.
\n\nโ Note
\n
All costs of signature requests created with your API keys will be charged to your business!
We recommend you to start with a demo API key for development and testing and switch to the production API key as soon as you are finished with testing.
\nIf you have problems setting up Skribble Business, just drop us an e-mail at
info@skribble.com
For a quickstart experience ...
\nUsing the Postman client, you will be able to execute first requests and simple examples and experience the basic usage of the Skribble API.
\nIn several example requests, PDF files or base64 encoded images files will be expected as input.
You will recognize these by the placeholder {{BASE64_PDF}} or {{BASE64_PNG}}.
Whenever you find this in an example request, you need either:
\n{{BASE64_PDF}} and {{BASE64_PNG}} to your Skribble API Quickstart environment.To encode your file base64, you can use local or any encoding tools available online.
\n\n\n","_postman_id":"3834aa8f-5fe8-4461-8b4f-47c9c989116b","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"4e11a066-f160-4d2e-839a-68463777126d","id":"4e11a066-f160-4d2e-839a-68463777126d","name":"๐ Quickstart","type":"folder"}}},{"name":"1. Create a SignatureRequest","item":[{"name":"Create a simple signature request for a PDF document","event":[{"listen":"test","script":{"id":"102fd61d-29a6-491f-ae23-afb3cc9afa13","exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","packages":{}}}],"id":"4dd248c5-1700-4812-977c-445d492fba5e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"message\": \"Please sign this document!\",\n \"content\": \"{{BASE64_PDF}}\",\n \"signatures\": [\n { \n\t\t\t\"account_email\" : \"you@example.info\"\n },\n {\n\t\t\t\"account_email\" : \"personOneToSign@external.net\"\n },\n {\n\t\t\t\"account_email\" : \"personTwoToSign@external.net\"\n } \n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/signature-requests","description":"Note
\n
Some base64 encoding tools add the data content/type or other prefixes to the value.
Please note that the base64 input fields only accept pure base64 encoded values.data:application/pdf;base64,JVBERi0xLjUKJcOkw7zDt.....
In this example this means that only the characters after the \",\" are valid.
In this example we have three signers. One of the signers is you and the other two are external signers. Of course, it is also possible to create signature requests in which you are the only signer or where you are not a signer yourself. In the second case, you as creator of the SignatureRequest get read-only rights on this data object.
The document workflow is quite easy.
You have one document and need one or more signatures. The document is private and not publicly available.
We need to create a SignatureRequest object in Skribble. A SignatureRequest is a description telling Skribble, who is going to sign what and optionally how the signature should look like.
So, let's start with the minimal information Skribble needs.
\nTell the user, what will be signed
The title should be short and treated like a file name. This field is mandatory.
Tell Skribble who will sign
The signatures array contains all signers of the document.
In the example, we have 3 signers. They can sign in any sequence they want, and the signature position and appearance will be defined by the Skribble web application.
All participants are informed at the same time and are allowed to sign the document in any order. The system ensures that the document is nevertheless only changed sequentially.
The account_email contains the user's e-mail address. It has two functions. All notifications are sent to this e-mail address AND the e-mail is used to find the user's ID in our database.
Tell Skribble which document will be signed
The content field contains the Base64 encoded bytes of the PDF document.
As an alternative to the content, you can give Skribble an URL using the field file_url, where it can download the document. The URL must not be used together with the content field.
All URLs passed to Skribble must use the HTTPS protocol.
\"file_url\" : \"https://myapp.com/path/to/document\"
\n\nSince we have a private document the recommended way is to transfer it to Skribble directly.
\n
\n\nThe maximum document size is about 40 MB, which results in the maximum request size of 60 MB.
\n
You will find more details to the SignatureRequest in the chapter Reference.
In this example we redirect the user to https://www.google.com and wait for max. 20 seconds to fullfil this request.
\n","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"fd3c2de4-cb53-4f49-a431-2025d7b82858","id":"fd3c2de4-cb53-4f49-a431-2025d7b82858","name":"2. Redirect the user to the Skribble web application","type":"folder"}},"urlObject":{"protocol":"https","path":["view","0000...2222"],"host":["my","skribble","com"],"query":[{"key":"exitURL","value":"https%3A%2F%2Fgoogle.com"},{"key":"redirectTimeout","value":"20"},{"key":"hidedownload","value":"true"}],"variable":[]}},"response":[{"id":"19ea229a-c664-4054-b2b4-a0f2c4442459","name":"Redirect after the signature process finished","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://my.skribble.com/view/0000...2222?exitURL=https%3A%2F%2Fgoogle.com&redirectTimeout=20","protocol":"https","host":["my","skribble","com"],"path":["view","0000...2222"],"query":[{"key":"exitURL","value":"https%3A%2F%2Fgoogle.com"},{"key":"redirectTimeout","value":"20"}]}},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"No response: You will be redirected to http://www.google.com"},{"id":"67c3d580-2eec-4058-8465-571de840585e","name":"Redirect in case of an error","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://my.skribble.com/view/0000...2222?errorURL=https%3A%2F%2Fbing.com","protocol":"https","host":["my","skribble","com"],"path":["view","0000...2222"],"query":[{"key":"errorURL","value":"https%3A%2F%2Fbing.com"}]}},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"No response: You will be redirected to http://www.bing.com"},{"id":"4d84a8b6-d274-4a58-9be6-d0543129dd7b","name":"Redirect after a signature request got declined","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://my.skribble.com/view/0000...2222?exitURL=https%3A%2F%2Fgoogle.com&redirectTimeout=20","protocol":"https","host":["my","skribble","com"],"path":["view","0000...2222"],"query":[{"key":"exitURL","value":"https%3A%2F%2Fgoogle.com"},{"key":"redirectTimeout","value":"20"}]}},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"No response: You will be redirected to http://www.google.com"}],"_postman_id":"28c6fa31-d6ea-4f31-b6f4-fa79926b7df9"}],"id":"fd3c2de4-cb53-4f49-a431-2025d7b82858","description":"The user has to visit the Skribble web application to actually sign the document.
\nWhen we created a Signature Request, the user got notified by Skribble that there is a document waiting to be signed.
\nNow we want to continue immediately and redirect the browser directly to Skribble showing the uploaded document.
\nSkribble provides a signing_url inside the SignatureRequest.
The signing_url not only points to the Skribble web application, but 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.
There are some more options available to tailor the signing flow to your application's specific needs.
\nAfter successfully signing the document, the user will stay on the Skribble web application.
\nHowever, you can add three different exit points as query parameters to the signing_url. Skribble will respect these parameters and redirect the user to the provided URLs once the signature process is finished.
Using this, you can bring the user back from Skribble to your application.
\nMake sure you encode your exit URLs properly. This is especially important for GET parameter separators like ? and & to ensure that they are not interpreted by browsers as GET parameters on Skribble's web application itself.
If exitURL is specified the user will be automatically redirected to the given URL after a successfull signature process. The default redirection timeout is 45 seconds.
Using the URL parameter redirectTimeout this duration can be adjusted.
Values equal or lower than 0 will cause the user to be redirected instantly, skipping Skribble's success page. For usability reasons the duration cannot be longer than 90 seconds. If a value higher than 90 is specified, the value will be set to 90.
\nThe success screen can be further simplified by hiding the download button. This minimises the chances that the user gets side tracked and won't follow through to the intended exitURL.
To hide the download button you must specify an exitURL as well as hidedownload. The actual value of hidedownload does not matter for it to be active.
Be aware that you have to offer the signed document as a download to the user in your application if you hide the download button on Skribble's interface.
\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"0b50a438-0c99-499e-824c-7b2be252a341"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"a149cf63-47c8-4ff0-97f1-82cf0998b4bf"}}],"_postman_id":"fd3c2de4-cb53-4f49-a431-2025d7b82858"},{"name":"3. Download the signed PDF document","item":[{"name":"Get the document ID from the signature request","event":[{"listen":"test","script":{"exec":["let docID = pm.response.json().document_id;\r","pm.environment.set(\"DOC_ID\", docID);"],"type":"text/javascript","id":"8af04b9c-132b-4065-8f4c-bab227a2b11f"}}],"id":"874d9e77-5bb4-4381-9252-925f538c5dbc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"GET","header":[],"url":"https://api.skribble.com/v2/signature-requests/{{SR_ID}}","description":"We distinguish between the signature request ID and document ID. To read and download the PDF document, the document ID is retrieved from the SignatureRequest with the ID {{SR_ID}}
Now you can download the document content that contains the PDF document with the document ID {{DOC_ID}}.
SignatureRequest that we created before contains the document_id.We can get the SignatureRequest with GET /v2/signature-requests/{SR_ID}
You will find the document ID inside the field document_id.
Finally, we can download the PDF document with a call to GET /v2/documents/{DOC_ID}/content.
\n\nNote
\n
Documents on Skribble are unchangeable (immutable).
Changes to the document content, like a completed signature, always lead to a NEW document with a NEW ID. This means that the document ID you receive after uploading a document, will differ from the ID you receive after downloading the document once it is signed .
You can find ways to get notified about changes on the SignatureRequest in the chapter Monitoring.
At some point, you need your customer to sign a document with Skribble.
\nThe document is generated on your platform for each customer individually and saved as a PDF document.
\nTo accomplish this, we will:
\nCreate a signature request.
\nRedirect the user to the Skribble web application.
\nRetrieve the signed document.
\ncontent_type are case sensitive. Be sure to send them in the correct case.null or none, as they may lead to unwanted changes on objects.In this example we create a SignatureRequest with the same signer who needs to sign the document twice. This forces the given signer to sign the PDF document twice to complete it.
In combination with Visual Signatures this might make sense in some cases when more than one signature on different pages of the document is required.
Instead of creating a SignatureRequest with predefined signatures, it is possible to start with an empty one and let a user modify the SignatureRequest on the Skribble web application.
To create an empty SignatureRequest omit the signatures array and provide a user with the rights to modify the SignatureRequest instead.
\nThe access rights to the SignatureRequest are granted by providing a write_access array containing one or more e-mail addresses for the users with full access.
\nOther settings can be provided as usual.
\nWhen visiting the URL provided in signing_url, the user can add signers and optionally define the appearance of the visual signature in the document, before the signature process continues as usual.
\n","urlObject":{"protocol":"https","path":["v2","signature-requests"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[{"id":"828a8c4e-2ced-41a3-90dc-6d37e35dd596","name":"Create a signature request without inital signers (200)","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"message\": \"Please sign this document!\",\n \"content\": \"Base64 encoded PDF file\",\n \"write_access\" : [\"john.doe@skribble.com\"]\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/signature-requests"},"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"cccccccc-4a6a-a958-a42e-6ea4172a378b\",\n \"title\": \"Example contract\",\n \"write_access\": [ \"john.doe@skribble.com\" ],\n ...\n}"}],"_postman_id":"09d0f0f3-5ed7-462a-b84b-a2ba6983fc3e"}],"id":"3eb5faf9-fae4-4dcb-8a8d-09dcd1043506","description":"As mentioned in the Quickstart chapter, it is possible to specify the number of signers.
Please refer to that chapter for an example.
The following special cases should be mentioned.
\nYou can precisely specify the position of one or more visual signatures in a document. The Skribble web application will enforce the use of this predefined position. In the background, Skribble will create an Acroform signature field at the specified position and place the signature in this new field.
\nIn this example, John Doe's signature can be set to appear in the lower-left corner of page 1 (page count starts at 0) and the lower right corner of page 2, while Karen Smith's signature might only appear on page 2. The origin of the coordinate system is at the bottom left corner of the page, with the x and y coordinates specifying the location of the bottom left corner of the visual signature. All units are in pixels.
\nNote: The visual signature information is unique to each signer, allowing you to mix and match them as necessary.
\nSummarized
\n\n\n","urlObject":{"protocol":"https","path":["v2","signature-requests"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[{"id":"ea8e1db4-b009-46fa-b9bf-52998829b4e4","name":"Define visual signatures using position data","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"message\": \"Please sign this document!\",\n \"content\": \"{{BASE64_PDF}}\",\n \"signatures\": [\n {\n \"account_email\": \"john.doe@example.com\",\n \"visual_signature\": {\n \"positions\": [\n {\n \"page\": \"0\",\n \"height\": 70,\n \"width\": 150,\n \"x\": 350,\n \"y\": 240\n }\n ]\n }\n },\n {\n \"account_email\": \"karen.smith@example.com\",\n \"visual_signature\": {\n \"positions\": [\n {\n \"page\": \"0\",\n \"height\": 70,\n \"width\": 150,\n \"x\": 50,\n \"y\": 230\n }\n ]\n }\n }\n ] \n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/signature-requests"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 19 Jun 2024 14:20:07 GMT","enabled":true},{"key":"Content-Type","value":"application/json;charset=UTF-8","enabled":true},{"key":"Transfer-Encoding","value":"chunked","enabled":true},{"key":"Connection","value":"keep-alive","enabled":true},{"key":"Expires","value":"0","enabled":true},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate","enabled":true},{"key":"X-XSS-Protection","value":"1; mode=block","enabled":true},{"key":"Pragma","value":"no-cache","enabled":true},{"key":"Location","value":"/api/signature-requests/6fcc3fac-515b-f4eb-0a12-87f76a4049e7","enabled":true},{"key":"X-Content-Type-Options","value":"nosniff","enabled":true},{"key":"Strict-Transport-Security","value":"max-age=15724800; includeSubDomains","enabled":true}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"cccccccc-ffff-eeee-0000-87f76a4049e7\",\n \"title\": \"Example contract\",\n \"message\": \"Please sign this document!\",\n ...\n \"signatures\": [\n {\n \"sid\": \"55555555-55555-4444-4444-837de87afb90\",\n \"account_email\": \"john.doe@example.com\",\n ...\n \"visual_signature\": {\n \"position\": {\n \"x\": 350,\n \"y\": 240,\n \"width\": 150,\n \"height\": 70,\n \"page\": \"0\",\n \"rotation\": 0,\n \"invisible\": false\n },\n \"positions\": [\n {\n \"x\": 350,\n \"y\": 240,\n \"width\": 150,\n \"height\": 70,\n \"page\": \"0\",\n \"rotation\": 0,\n \"invisible\": false\n },\n {\n \"x\": 400,\n \"y\": 60,\n \"width\": 150,\n \"height\": 70,\n \"page\": \"0\",\n \"rotation\": 0,\n \"invisible\": false\n }\n ]\n }\n },\n {\n \"sid\": \"88888888-1d8d-5555-8888-85b7a8650074\",\n \"account_email\": \"karen.smith@example.com\",\n ...\n \"visual_signature\": {\n \"position\": {\n \"x\": 50,\n \"y\": 230,\n \"width\": 150,\n \"height\": 70,\n \"page\": \"0\",\n \"rotation\": 0,\n \"invisible\": false\n },\n \"positions\": [\n {\n \"x\": 50,\n \"y\": 230,\n \"width\": 150,\n \"height\": 70,\n \"page\": \"0\",\n \"rotation\": 0,\n \"invisible\": false\n }\n ]\n }\n }\n ],\n ...\n}"},{"id":"f143de2f-c31b-4ee4-a764-7e0d76ca94d7","name":"Define visual signatures with page out of range","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"message\": \"Please sign this document!\",\n \"content\": \"{{BASE64_PDF}}\",\n \"signatures\": [\n {\n \"account_email\": \"john.doe@example.com\",\n \"visual_signature\": {\n \"positions\": [\n {\n \"page\": \"0\",\n \"height\": 70,\n \"width\": 150,\n \"x\": 350,\n \"y\": 240\n },\n {\n \"page\": \"1\",\n \"height\": 70,\n \"width\": 150,\n \"x\": 400,\n \"y\": 60\n }\n ]\n }\n },\n {\n \"account_email\": \"karen.smith@example.com\",\n \"visual_signature\": {\n \"positions\": [\n {\n \"page\": \"1\",\n \"height\": 70,\n \"width\": 150,\n \"x\": 50,\n \"y\": 230\n }\n ]\n }\n }\n ] \n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/signature-requests"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 19 Jun 2024 14:18:48 GMT","enabled":true},{"key":"Content-Type","value":"application/json","enabled":true},{"key":"Transfer-Encoding","value":"chunked","enabled":true},{"key":"Connection","value":"keep-alive","enabled":true},{"key":"Expires","value":"0","enabled":true},{"key":"Cache-Control","value":"no-cache, no-store, max-age=0, must-revalidate","enabled":true},{"key":"X-XSS-Protection","value":"1; mode=block","enabled":true},{"key":"Pragma","value":"no-cache","enabled":true},{"key":"X-Content-Type-Options","value":"nosniff","enabled":true},{"key":"Strict-Transport-Security","value":"max-age=15724800; includeSubDomains","enabled":true}],"cookie":[],"responseTime":null,"body":"{\n \"type\": \"https://api.skribble.com/problem/problem-with-message\",\n \"status\": 400,\n \"message\": \"position.page references a non existing page in the document\",\n \"method\": \"POST\",\n \"path\": \"/v2/signature-requests\"\n}"}],"_postman_id":"bb3fb9b1-e806-4447-8ee6-5202e6f0e558"},{"name":"Define visual signatures using PDF Form Fields","event":[{"listen":"test","script":{"id":"68e6c600-9d46-4023-8714-cbe05c90952f","exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","packages":{}}}],"id":"97bcffc4-bbe5-465c-afb5-662f5d431795","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"message\": \"Please sign this document!\",\n \"content\": \"{{BASE64_PDF}}\",\n \"signatures\" : [\n {\n \"account_email\" : \"john.doe@skribble.com\",\n \"visual_signature\" : {\n \"form_field\" : \"Person_1\"\n }\n },\n {\n \"account_email\" : \"karen.smith@skribble.com\",\n \"visual_signature\" : {\n \"form_field\" : \"Person_2\"\n }\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/signature-requests","description":"Note
\n
In the current version of theSignatureRequestresponse, you will find both thepositionfield, which contains a position object, and thepositionsfield, which contains an array of position objects. This is for compatibility reasons. By including both fields, we ensure that API v1 users receive apositionobject, even if thepositionsarray was used when creating theSignatureRequest.
PDF documents let you add form fields to a document. If a PDF document contains signature form fields, you can tell Skribble to make these fields mandatory for a signer.
\nIn the example, John Doe must sign in the form field Person_1 and Karen Smith in the field Person_2. The Skribble web application will enforce the usage of the fields.
\nThe PDF Acroform field must be of type signature and not of any other type. A form field defines fixed positions in the document. One signature can be displayed zero, one or more times on one or more pages throughout the document.
\nIt does not define what the contents of the field will show. This is handled by the Skribble web application.
\nThe advantage of PDF form fields is that a document designer can size and position the fields perfectly in a document before the document is used in any project.
\n","urlObject":{"protocol":"https","path":["v2","signature-requests"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"97bcffc4-bbe5-465c-afb5-662f5d431795"}],"id":"6996b790-db09-4e0c-ac26-f7af42a594e2","description":"The visual signature on a PDF document is an optional element that does not affect the legal validity of the electronic signature. The decision to add a visual signature is at the discretion of the inviter. Including a visual signature can maintain the appearance of a handwritten signature and provide additional information about the signer.
\nIf a signature request lacks specific instructions for a visual signature, the user can create and place a visual signature anywhere on the document using the Skribble web application. This flexibility mirrors how physical documents handle signature placement, where visual hints like \"Please sign here\" are helpful but not required.
\nIn the digital world, we have some more options.
\nMultiple visual signatures
\nVisual signatures can be placed multiple times within a document, similar to how one might need to sign in various locations on a physical document. The advantage of this approach is that the signatory only needs to sign once using the Skribble web application. All visual signatures in the document are then linked to this single electronic signature.
\n","_postman_id":"6996b790-db09-4e0c-ac26-f7af42a594e2"},{"name":"Provide PDF file to sign","item":[{"name":"Create a signature request including a document upload","event":[{"listen":"test","script":{"id":"bdf15ad7-5a3e-47df-83f7-bde04a9b4897","exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);","let documentID = pm.response.json().id;","pm.environment.set(\"DOCUMENT_ID\", documentID);",""],"type":"text/javascript","packages":{}}}],"id":"81f32173-bb21-47d5-be1d-70fbab6882c1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"signatures\": [\n {\n \"account_email\" : \"john.doe@skribble.com\"\n }\n ],\n \"content\" : \"{{BASE64_PDF}}\" \n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/signature-requests","description":"This request creates a simple SignatureRequest containing one signer.
In this case the PDF document gets uploaded as Base64 encoded file using the field content.
As an alternative to the document upload, the Skribble API allows you to refer to an online PDF document. Please use the field file_url.
\n\n","urlObject":{"protocol":"https","path":["v2","signature-requests"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[{"id":"358e3025-6bba-432e-a3fe-7615a7f90f3e","name":"Create signature request with a document reference (200)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","name":"Content-Type","type":"text"}],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"signatures\": [\n {\n \"account_email\": \"john.doe@skribble.com\"\n }\n ],\n \"file_url\": \"https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/signature-requests"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","name":"Content-Type","description":"","type":"text","enabled":true}],"cookie":[],"responseTime":null,"body":"{\r\n \"id\": \"dddddddd-ab69-4b50-c174-ffffffffffffff\",\r\n \"title\": \"Example contract\",\r\n \"message\": \"Please sign this document!\",\r\n \"document_id\": \"99999999-0101-0202-7744-a829913fccf5\",\r\n ...\r\n}"}],"_postman_id":"0d232920-41ec-4c26-bf6d-185e4ec30a05"},{"name":"Create a signature request for an uplaoded document","event":[{"listen":"test","script":{"id":"db46c826-9957-43ba-9165-fb31b1e44f6d","exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","packages":{}}}],"id":"e08a408b-ac79-4b21-abba-88b836c486cd","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{"content-type":true}},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"signatures\": [\n {\n \"account_email\": \"john.doe@skribble.com\"\n }\n ],\n \"document_id\": \"{{DOC_ID}}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/signature-requests","description":"Please ensure that you use the field
\nfile_urlwithout thecontentfield.
All URLs passed to Skribble must use the HTTPS protocol.
In some rare cases it might be helpful for you to provide the document separately and not directly with the SignatureRequest. For more information, see the chapter Reference > Documents
So, if you have already provided a document to Skribble and want to create a SignatureRequest for this document, you can do this by passing the document ID in the field document_id.
\n\n","urlObject":{"protocol":"https","path":["v2","signature-requests"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[{"id":"763ec2a5-1a57-4513-9c6f-d965542ff761","name":"Create signature request for uploaded document (200)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","name":"Content-Type","type":"text"}],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"signatures\": [\n {\n \"account_email\": \"john.doe@skribble.com\"\n }\n ],\n \"document_id\": \"{{DOC_ID}}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/signature-requests"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","name":"Content-Type","description":"","type":"text","enabled":true}],"cookie":[],"responseTime":null,"body":"{\r\n \"id\": \"dddddddd-ab69-4b50-c174-ffffffffffffff\",\r\n \"title\": \"Example contract\",\r\n \"message\": \"Please sign this document!\",\r\n \"document_id\": \"99999999-0101-0202-7744-a829913fccf5\",\r\n ...\r\n}"}],"_postman_id":"e08a408b-ac79-4b21-abba-88b836c486cd"}],"id":"850c564a-6f1e-4e49-b7b9-725cce1dd0e6","description":"Please ensure that you use the field
\ndocument_idwithout thecontentorfile_urlfield.
The Skribble API supports different ways of providing the PDF document for signing.
\n","_postman_id":"850c564a-6f1e-4e49-b7b9-725cce1dd0e6"},{"name":"Define the signature quality and legislation","item":[{"name":"Create a signature request with quality and legislation","event":[{"listen":"test","script":{"id":"b8ecd41d-d4ef-4888-a417-fb741dd109fb","exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","packages":{}}}],"id":"77ed43f0-a6ff-4a49-a50e-5ebca751b01a","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{}},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"title\": \"Create test SigntureRequest\",\n \"signatures\": [\n {\n \"account_email\": \"john.doe@skribble.com\"\n }\n ],\n \"content\": \"{{BASE64_PDF}}\",\n \"quality\": \"AES\",\n \"legislation\": \"ZERTES\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/signature-requests","description":"In this example we create a SignatureRequest using the quality AES and the legislation ZERTES to sign a document.
Skribble supports different levels of signature qualities โ the so-called e-signature standards. For more information on when to use which e-signature standard, visit our website.
\nThe selected signature quality for the document is determined by two parameters: quality and legislation.
The parameter quality supports the following values:
\n\nNote
\n
The qualitiesQESandAES_MINIMALmust provide alegislationparameter, because the QES is bound to legal regulations, which are different in Switzerland and the EU.
The legislation parameter correspond to the following values:
\n","_postman_id":"d7e2129b-e58f-4e73-b8d0-59ffbc975501"},{"name":"Signing without an account","item":[{"name":"Create a signature request for a \"No-Account-Signer\"","event":[{"listen":"test","script":{"id":"6241bd15-1353-4a2d-9466-98a04b9a42f1","exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","packages":{}}}],"id":"919871cc-0fe0-442c-b25d-2d984e169f4e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"title\": \"Create test SignatureRequest for a no account signer\",\n \"signatures\": [\n {\n \"signer_identity_data\": {\n \"first_name\": \"Noah\",\n \"last_name\": \"Count\",\n \"mobile_number\": \"41799885566\"\n }\n }],\n \"content\": \"{{BASE64_PDF}}\",\n \"quality\": \"AES\",\n \"legislation\": \"ZERTES\"\n }","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/signature-requests","description":"In this example, we create a SignatureRequest for a document that will be signed using the quality AES and the legislation ZERTES.
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 create a SignatureRequest for a user without an account, omit the signatures array entry for this user and provide the necessary data using the signer_identity_data element instead.
Other settings can be provided as usual, e.g. callback URLs, documents and so on.
\nEach 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.
\n\n๐ก Good to know
\n
We recommend this approach of combiningsigner_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 an existing Skribble account. Instead, they will have to access the document using the specific link provided in their signature invitation email.
When the user visits the URL provided in the field signing_url inside the signature element, he will be forwarded to a special preview page of the PDF document and can start the signature process as usual.
Missing fields like first name and last name can easily be adjusted by the signer through the Skribble web client.
\n\n\nPlease note that you do not mix up the
\nsigning_urlinside thesignaturefield with thesigning_urlon the top level of the response. This contains the default URL for users with a regular Skribble account .
Skribble will display its content in the user's browser language by default. You can change the language by adding a lang parameter to the signing_url when calling the browser.
\n\nExample for a
\nlangparameter
my.skribble.com/view/some-id-000-00000/some-id-fff-fffff?lang=fr
To determine in which language the e-mails are sent to the user, the parameter language can be added to signer_identity_data.
Skribble supports the following languages:
\n","_postman_id":"bab0a0bf-ad61-4d46-8e04-ceee410199c8"}],"id":"893aebed-59ba-4706-bb3e-09af4e482152","_postman_id":"893aebed-59ba-4706-bb3e-09af4e482152","description":""},{"name":"โ Extended options","item":[{"name":"Define observers","item":[{"name":"Create a signature request and add observers","event":[{"listen":"test","script":{"exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","id":"ac6cc34c-abc5-4b45-bcb2-adffab65e168"}}],"id":"cc3f8255-47b7-4278-963e-34bbe2edacd0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"content\": \"{{BASE64_PDF}}\",\n \"cc_email_addresses\": [\"observer1@skribble.com\", \"observer2@skribble.com\"],\n \"signatures\": [\n {\n \"account_email\": \"john.doe@skribble.com\"\n }\n ]\n}"},"url":"https://api.skribble.com/v2/signature-requests","description":"To add one or more observers you can use the field cc_email_addresses. This field must contain an array of user email addresses. The observers need to have a valid Skribble account. Otherwise the email address will not be accepted as valid observer.
In this example we create a SignatureRequest with two observers, observer1@skribble.com and observer2@skribble.com.
Skribble allows observers to be added to a SignatureRequest. Observers are given read access on the SignatureRequest and will be notified in the same way about activities on the SignatureRequest as a signer of the SignatureRequest.
\n\n","_postman_id":"45676b7d-e5e1-411b-8cf5-d92b5478786a"},{"name":"Disable notification e-mails","item":[{"name":"Create a signature request and disable e-mail notifications for one signer (200)","event":[{"listen":"test","script":{"exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","id":"76e8bb2b-69af-440b-99b0-538cd8028b9e"}}],"id":"53b8b488-1500-48cd-b19f-24a17a90d2b5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"content\": \"{{BASE64_PDF}}\",\n \"signatures\": [\n {\n \"account_email\": \"john.doe@skribble.com\"\n },\n {\n \"account_email\": \"charles.doe@skribble.com\",\n \"notify\": false\n }\n ]\n}"},"url":"https://api.skribble.com/v2/signature-requests","description":"Note
\n
The given observers need to have a valid Skribble account. Otherwise the email address will not be accepted as valid observer.
In this example we create a SignatureRequest with two signers.
For the second signer, we disable ALL the e-mail notifications this signer would usually receive by Skribble, such as the invitation e-mail to this SignatureRequest or the notification e-mail that all signers have signed the document. \nTo disable the e-mail notifications you can use the field \"notify\": false individually for each signer.
\n\n","urlObject":{"protocol":"https","path":["v2","signature-requests"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"53b8b488-1500-48cd-b19f-24a17a90d2b5"}],"id":"48c19a95-e6af-4204-97e8-1e2ca055545e","description":"Please keep in mind, that it is in your responsability to inform the users about the status of the 'SignatureRequest' when you use this feature.
\n
Skribble takes over the communication with all participants of a SignatrueRequest, such as the creator or the different signers. It informs the respective participants by e-mail about changes in the status of the SR.These notifications are activated by default, but can be deactivated by a parameter.
The attach_on_success field can be used to define what type of document should be attached to the \"all-signatures-completed\" notification e-mail. The field is an array that can contain the following entries as a string.
If members are allowed by business setting to decide whether to attach the documents or not, it is possible to prevent one or both document types from being sent by removing them from the attach_on_success array.
In the case that the default setting is, that one or both documents should be attached AND it is additionally allowed to change this behaviour by the business members, it is possible to define that the document should not be attached by removing the document type from the array.
\nExample:
\nIf the attach_on_success array is empty in the described case (attach_on_success=[]), then NO documents are attached at all.
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:
\nThis 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 the SignatureRequest field attach_on_success.
In this example we define the user defined in the field creator (some-member-of@your-buiness.com) as new owner of this SignatureRequest.
Generally, all SignatureRequest objects are created by an API user, who then typically becomes the owner of these objects.
However, in some specific cases, you might want to designate a business member as the owner of a SignatureRequest. For instance, if you have an interface for one of your company applications, you may want the application user to become the owner of the SignatureRequest when they initiate a signing process.
This is possible, but only if two conditions are met:
\n\n\n","_postman_id":"9f378c67-0c8f-4adb-b23f-4f2ce26a12f3"},{"name":"Define a signing sequence","item":[{"name":"Create a signature request and set a signing sequence","event":[{"listen":"test","script":{"exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);"],"type":"text/javascript","packages":{},"id":"372d541b-0e31-42b2-b10f-6b19932e91e9"}}],"id":"bbc01b6c-d189-4824-bb5d-bf6f5c85de62","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"title\": \"Example contract\",\r\n \"message\": \"Please sign this document\",\r\n \"content\": \"{{BASE64_PDF}}\",\r\n \"content_type\": \"application/pdf\",\r\n \"quality\": \"SES\",\r\n \"signatures\": [\r\n {\r\n \"account_email\": \"first@example.com\",\r\n \"sequence\": 1 \r\n },\r\n {\r\n \"account_email\": \"secondA@example.com\",\r\n \"sequence\": 2\r\n }, \r\n {\r\n \"account_email\": \"secondB@example.com\",\r\n \"sequence\": 2\r\n }, \r\n {\r\n \"account_email\": \"thirdA@example.com\",\r\n \"sequence\": 3\r\n },\r\n {\r\n \"account_email\": \"thirdB@example.com\",\r\n \"sequence\": 3\r\n },\r\n {\r\n \"account_email\": \"fourth@skribble.com\",\r\n \"sequence\": 4\r\n }\r\n ]\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/signature-requests","description":"๐ก Good to know
\n
Even after changing the owner, the API user will remain a participant of theSignatureRequestobject with read and write access. This allows the API user to continue performing actions such as modifying or retrieving theSignatureRequestobject.
Using the sequence field, it is possible to define a signing sequence for signers.
In order to use the sequence, the following rules MUST be observed:
sequence starts with 1.1 for the first signer, 2 for the second signer and so on.It may be the case that certain contracts or documents must be signed by the signatories in a certain sequence.
\n","_postman_id":"cd7e21d4-0df6-4d79-814f-661b23e03ce5"},{"name":"Disable TAN based NAS notifications for SES","item":[{"name":"Create a signature request and disable NAS notification","event":[{"listen":"test","script":{"exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);"],"type":"text/javascript","packages":{},"id":"1c5306fa-8d04-41c3-879e-eba109ad5173"}}],"id":"30b05e08-8388-4365-bd0a-ec6963b36cc2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"title\": \"Example contract\",\r\n \"message\": \"Please sign this document\",\r\n \"content\": \"{{BASE64_PDF}}\",\r\n \"content_type\": \"application/pdf\",\r\n \"quality\": \"SES\",\r\n \"signatures\": [\r\n {\r\n \"notify\": false,\r\n \"signer_identity_data\": {\r\n \"email_address\": \"nas@example.com\",\r\n \"identity_reference\": \"Internal-ID-012345\"\r\n }\r\n }\r\n ]\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/signature-requests","description":"Provide the link provided in the field signatures.signing_url to your users in order to continuw with the signing process.
In combination with SES, Skribble offers a straightforward TAN-based validation for the email addresses of No-Account-Signers.
\nThis mechanism can be disabled by setting the field notify to false and additionally using the field signer_identity_data.identity_reference which can hold a customer generated value for further identtification.
This means that No-Account-Signers can sign directly without needing the additional Skribble TAN process.
\nThis option enables you to either handle user identification themselves or to simply jump in as guarantee for your users.
\n","_postman_id":"e89788ab-3a8a-4ea4-94b3-8fb8918bb157"}],"id":"a6a9afbd-95e9-48c9-b779-dc8c11363cf7","_postman_id":"a6a9afbd-95e9-48c9-b779-dc8c11363cf7","description":""}],"id":"f74202ac-a7df-459e-b4bc-a2075341fa47","description":"In this chapter we will discuss the options available to create a SignatureRequest
Using this GET request, you can list all the SignatureRequests provided that the current user has sufficient access rights to.
You can optionally filter these SignatureRequests using one or more of the following criteria.
\n\nNote
\n
The filter searches for an exact match of the corresponding field content. This means that the filter is case sensitive and won't find objects that only contain the parameter. For example account_email=john.doe@skribble.com will only find aSignatureRequestswhere the fieldaccount_emailis exactly <em>john.doe@skribble.com</em>. It won't find <em>another.john.doe@skribble.com</em>
Exception: The search parameter searches for document titles that contain the search term.
Pagination
\nFurthermore, the result set can be controlled using the optional pagination parameters page_number and page_size, which helps prevent excessively large result sets.
The List SignatrueReuest by bulk endpoint allows clients to retrieve multiple SignatureRequest objects in a single call.
Provide a JSON array of SignatureRequest IDs in the request to specify which SignatureRequests to fetch.
The response includes only the SignatureRequests that were successfully found. SignatureeRequest IDs not matching existing records are silently ignored.
Using this GET request, you can query one single SignatureRequest by using the signature request ID.
A SignatureRequest as well as the single Signatures can be in different states.
The state of the SignatureRequest can be found in the field status_overall.
The single Signatures contains its state ind the field signatures[].status_code
The SignatureRequest and the Signatures can take one of the following states:
\n\n","_postman_id":"b121651b-3ebc-4484-9f3c-c414a55a90c8"},{"name":"Modify","item":[{"name":"Add or remove signers","item":[{"name":"Add or remove multiple signers simultaneously","id":"c1a29021-bb26-40af-9bd2-c4a774e4a18d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"PUT","header":[],"body":{"mode":"raw","raw":"{\r\n \"id\": \"{{SR_ID}}\",\r\n \"title\": \"NewTitleTest\",\r\n \"signatures\": [\r\n {\r\n \"account_email\": \"john.doe@skribble.com\"\r\n },\r\n {\r\n \"account_email\": \"new.signer@skribble.com.org\"\r\n }\r\n ]\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/signature-requests","description":"Note
\n
The signature states are managed by the system. It has informal value and cannot be changed using the API.
To add or remove multiple signers at once, you need to update the signatures array according to your needs.
To add a signer to the SignatureRequest, simply add a new entry to the signatures array.
To remove a signer from the SignatureRequest, simply remove the corresponding entry from the signatures array.
\n\nโ ๏ธ IMPORTANT NOTE
\n
Please be aware that if you want to add one or more new signers, you MUST include the existing signers in the update request. Any signers not present in the signatures array will be removed!
Changes to the signatures can only be made as long as none of the signers have already completed the signature.
\nTo 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}}.
\n\n","urlObject":{"protocol":"https","path":["v2","signature-requests","{{SR_ID}}","signatures"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"20c99183-10a0-4142-a763-b3b91d4854db"},{"name":"Remove an individual signer","id":"f3170c1e-1ebe-4b52-ad25-bb4fac976f3d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"DELETE","header":[],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/signature-requests/{{SR_ID}}/signatures/{{SID}}","description":"๐ก Good to know
\n
We recommend this approach of combiningsigner_idendity_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 an existing Skribble account. Instead, they will have to access the document using the specific link provided in their signature invitation email.
To remove an individual signer, provide the SignatureRequest ID {{SR_ID}} and the Signature ID {{SID}} of the signer you want to remove.
The Skribble API provides several methods for adding or removing signers from a SignatureRequest object. You can add or remove signers individually or update multiple signers simultaneously.
\n","_postman_id":"ff7e31d5-6fed-44dd-bd88-0bbf54a02cdb"},{"name":"Add or remove attachments","item":[{"name":"Add an attachment to a signature request","event":[{"listen":"test","script":{"exec":["let attachment_id = pm.response.json().attachments[0].attachment_id;","pm.environment.set(\"ATTACHMENT_ID\", attachment_id);"],"type":"text/javascript","packages":{},"id":"28a3afc0-5d63-49d4-981d-5c2b45591633"}}],"id":"8f8b71fd-3a23-4e88-b770-ea83090e41f2","protocolProfileBehavior":{"disabledSystemHeaders":{},"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"filename\": \"some_attachment_with_somename.pdf\",\r\n \"content_type\": \"application/pdf\",\r\n \"content\": \"{{BASE64_PDF}}\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/signature-requests/{{SR_ID}}/attachments","description":"The following request uploads a PDF file and attaches it to the SignatureRequest with the ID {{SR_ID}}
The field content_type defines one of the allowed content-types application/pdf of the uploaded file
The filename field specifies the name under which the file will be displayed to the participants of the SignatureRequest.
Downloads the attachment content with the ATTACHMENT_ID for the SignatureRequest with the ID SR_ID
Delete the attachment with the ATTACHMENT_ID from the SignatureRequest with the ID SR_ID
You may need to provide participants with additional information in the form of supplementary documents, such as Terms & Conditions or appendix documents.
\nIn this case, you can use the attachment endpoints to provide such documents through the SignatureRequest to the participants of the SignatureRequest.
Limits by content-type
\nThe Skribble API accepts files of the type PDF, image files, Microsoft Office files and plain text types.
\nDetailed list of the allowed content_types:
application/pdfapplication/x-tika-msofficeapplication/x-tika-ooxmlapplication/mswordapplication/vnd.openxmlformats-officedocument.wordprocessingml.documentapplication/vnd.ms-word.document.macroEnabled.12application/vnd.ms-excelapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheetapplication/vnd.ms-excel.sheet.macroenabled.12application/vnd.ms-powerpointapplication/vnd.openxmlformats-officedocument.presentationml.presentationapplication/vnd.ms-powerpoint.presentation.macroEnabled.12image/gifimage/jpegimage/pngtest/plainLimits by content-size
\nThe maximum size of one attachment file is equal to the the maximum document size of a PDF, which is about 40 MB, which results in the maximum request size of 60 MB.
\nLimits by amount
\nSkribble currently does not limit the number of attachments per SignatureRequest. However, if we observe abuse of this service, we will take appropriate measures.
\n","_postman_id":"93e02209-d04e-4460-a9cc-3e081fd93454"},{"name":"Delete a signature request","event":[{"listen":"test","script":{"exec":[""],"type":"text/javascript","id":"c7865066-6f20-4a11-ac57-0f3971ec04d9"}}],"id":"beedd756-f48a-4a59-920a-09cad1226c0a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"DELETE","header":[],"url":"https://api.skribble.com/v2/signature-requests/{{SR_ID}}","description":"By using the signature request ID you can delete a SignatureRequest.
Important: A SignatureRequest can only be deleted using the API, if:
SignatureRequest is in the status_overall=OPEN andSignatureRequest, eg. when it was created by the API user.Deleting a SignatureRequest does not necessarily remove the SignatureRequest from the system.
WITHDRAWN
When the API user is the owner of the SignatureRequest and the SignatureRequest is still in the status_overall=OPEN then the SignatureRequest will be WITHDRAWN.
This means that the SignatureRequest will get status_overall=WITHDRAWN and all the invited signatures will be marked with status_code=WITHDRAWN. Sign and read rights for the signers will be removed from the SignatureRequest, so that the invited signers can neither read nor sign the SignatureRequest any more.
REMOVE AS PARTICIPANT
When the API user is NOT the owner of the document but a participant of the SignatureRequest, then the DELETE request will only remove the current API user as participant from the signature request. \nIn this case the system will remove the objects the SignatureRequest and the related document as soon as the last remaining user deletes the SignatureRequest using the Skribble web application
DELETING
When the API user is the last user with access rights to the SignatureRequest e.g. after a WITHDRAW request, then the SignatureRequest and the related document will be completely removed from the system.
Sometimes, signing a document may become unnecessary, or errors might occur during the invitation process. As the inviter of such a SignatureRequest, you can explicitely withdraw the SignatureRequest. Withdraw removes all signatories and observers from the document as participants and notifies them with a specified message.
Similar to deletion, the withdraw action can only be executed if:
status_overall=OPENSignatureRequest, such as when it was created by the API user.\n\n","urlObject":{"protocol":"https","path":["v2","signature-requests","{{SR_ID}}","withdraw"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"65b879fe-43ad-40bf-98a0-fe3323fcbe56"}],"id":"62e66b7c-e308-41ee-9e8a-11f03fc1a526","description":"Note
\n
We recommend using thedeleteendpoint. By default, it checks for other options. For example, if the API user does not have withdrawal rights, the user could be removed from theSignatureRequestdirectly, or the document might be deleted directly.
Nevertheless, there may be situations in which you need to withdraw the document and keep it in Skribble. In this case you should of course use thewithdrawfunctionality.
Modifications on existing SignatureRequests should be handled with care.
We recommend creating the SignatureRequests with all necessary information.
In addition to the automatic signature reminders, manual reminders can also be initiated via the Skribble web application and also via the API.
\nThis 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.
\nLimits
\nThere 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.
\n","urlObject":{"protocol":"https","path":["v2","signature-requests","{{SR_ID}}","remind"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"d70ed206-dc9f-42d2-b864-a10f2572fbac"}],"id":"0d374d62-7b6b-4b3d-99c9-9871528aa7fa","description":"Triggering actions on SignatureRequests should be handled with care to avoid spamming your users or customers.
\n","_postman_id":"0d374d62-7b6b-4b3d-99c9-9871528aa7fa"},{"name":"Object details","item":[],"id":"8f26d5c1-e5fe-4af3-9994-a93c6163c7e7","description":"Beside the described examples, you can find all available fields to create or modify a SignatureRequest here in the detailed object descriptions.
When you request a SignatureRequest object you will receive the following information within the object.
Provides the signature report for a specific signature request.
\nBy 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.
\n","urlObject":{"protocol":"https","path":["v2","signature-requests","{{SR_ID}}","report"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[{"id":"0fdf3f25-4029-4436-947d-d8d1cc420691","name":"200 PDF","originalRequest":{"method":"GET","header":[],"url":"https://api.skribble.com/v2/signature-requests/{{SR_ID}}/report"},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"server","value":"nginx"},{"key":"date","value":"Thu, 22 Jan 2026 07:53:26 GMT"},{"key":"content-type","value":"application/json"},{"key":"transfer-encoding","value":"chunked"},{"key":"x-content-type-options","value":"nosniff"},{"key":"x-xss-protection","value":"0"},{"key":"cache-control","value":"no-cache, no-store, max-age=0, must-revalidate"},{"key":"pragma","value":"no-cache"},{"key":"expires","value":"0"},{"key":"x-frame-options","value":"DENY"},{"key":"access-control-allow-headers","value":"*"}],"cookie":[],"responseTime":null,"body":"PDF document as raw bytes."}],"_postman_id":"cd6deb59-5d9f-47e7-9bf7-99b3bdfed8ed"}],"id":"b3a13457-54de-4857-b414-b0ba0bf4e756","_postman_id":"b3a13457-54de-4857-b414-b0ba0bf4e756","description":""}],"id":"b6100136-63b3-4fd6-a703-3a0848a89c04","description":"The SignatureRequest object is the primary object of the Skribble API .
It describes who signs what and how. It gives an overview of the current state of the single Signatures and allows to control user rights or callback functionality.
\n\n","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"36cb8245-9b31-427f-a3ff-f3df161b0e3e"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"81b79b58-406c-42fd-ab29-85b922b7aa33"}}],"_postman_id":"b6100136-63b3-4fd6-a703-3a0848a89c04"},{"name":"Seal","item":[{"name":"Create","item":[{"name":"Seal a document","event":[{"listen":"test","script":{"id":"6e0d3972-cf35-4b13-8018-9a7f40dc3754","exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","packages":{}}}],"id":"72ed542c-7e2a-4140-ae03-27780b78acf7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"content\": \"{{BASE64_PDF}}\",\n \"visual_signature\": {\n \"position\": {\n \"x\": 20,\n \"y\": 20,\n \"width\": 260,\n \"height\": 120,\n \"page\": \"0\"\n },\n \"image\": {\n \"content_type\": \"image/png\",\n \"content\": \"{{BASE64_PNG}}\"\n }\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/seal","description":"Note
\n
In the following chapters we will discuss some of the options to work withSignatureRequest. The examples are tailored to the respective topic, but can be combined in one request, if necessary.
In this example we seal the document with a visual signature including an image. This represents the visual seal of the company.
\n","urlObject":{"protocol":"https","path":["v2","seal"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[{"id":"02173359-31c0-4940-a870-ad7a1c772647","name":"Seal a document (200)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","name":"Content-Type","type":"text"}],"body":{"mode":"raw","raw":"{\n \"content\": \"{{BASE64_PDF}}\",\n \"visual_signature\": {\n \"position\": {\n \"x\": 20,\n \"y\": 20,\n \"width\": 260,\n \"height\": 120,\n \"page\": \"0\"\n },\n \"image\": {\n \"content_type\": \"image/png\",\n \"content\": \"{{BASE64_PNG}}\"\n }\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/seal"},"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"{\n \"document_id\": \"e4cde459-6e63-0095-10b8-55b39ec39f46\"\n}"}],"_postman_id":"72ed542c-7e2a-4140-ae03-27780b78acf7"},{"name":"Seal a document with a specific seal","event":[{"listen":"test","script":{"id":"0214da1f-9282-4605-9a19-bf2be2a47069","exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","packages":{}}}],"id":"21c0290e-d05d-4d2b-bb1b-3d8dc5691fb9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"content\": \"{{BASE64_PDF}}\",\n \"account_name\": \"ais_company_seal_some_department\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/seal","description":"If your organisation is owner of multiple seals e.g. one seal for each department of you organisation, then you might want to define the seal that should be used for sealing the document. You can do so by using the field account_name. This field contains the name of the account Skribble did set-up for your organization seal.
When you use a demo API key for sealing, a demo seal is generated by default. \nLike the demo signature, a demo seal has no legal binding and is intended for testing and demo purposes only. \nFor testing purposes, you can also use the account_name field to generate demo keys via production API. You can do this by specifying the value ais_demo_seal in the field account_name.
Uploading and affixing an electronic seal to a document takes just one call using the /v2/seal resource.
The JSON is similar to the SignatureRequest. It requires only the PDF document as a Base64 encoded string in the content field.
Additionally, you can place a visual signature on the document, as described in the Visual Signatures chapter of the Skribble API documentation, but this is optional.
\nAn API response from a seal request contains a document_id of the newly created document with the seal.
Use the GET /v2/documents resource to retrieve the document with the electronic seal or reuse it in further signature requests, such as for personal electronic signatures.
Beside the described examples, you can find all available fields to create a seal here in the detailed object descriptions.
An electronic seal can be considered as an electronic signature for a legal entity (business or organisation), and not a natural person.
\nThe possability of sealing is thus only available to Skribble Business and Enterprise customers.
With a demo API key you are already able to create a demo seal.
For a real organisation seal you need to set-up and activate a seal at Skribble.
For more information on set-up and activation, please visit the chapter Manage electronic seals on the Skribble Admin guide.
Start the signing process by uploading the PDF document content and assigning it a title.
\n\nSign-To objects and its related Documents and SignatureRequests are only guaranteed for a limited lifetime.
\n
Sign-To request that dont get claimed by a user, so where a user does not add the document to the list of his documents to sign, will be deleted automatically after one day.
\nSign-To objects and its related Documents and SignatureRequest objects in general, independant of its status, will be deleted automatically after 90 days.
\nTo 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.
As response you will get the initially provided PDF document in its current state. This might be signed, declined or withdrawn or still open for signing. The status can be obtained using the track endpoind.
With the track endpoint, you can retrieve and monitor the status of the generated Send-To object at any time.
To delete a Sent-To object based on its ID you must include the value of the access_code fieldโreceived when creating the Send-To objectโin the request header X-Accesscode.
This call deletes the involved Send-To, Document and SignatureRequest objects regardeless the current Send-To state.
Initiate the signing process without the need for an API key
\nUsing this Send-To approach Skribble provides a way for external parties to start the signing process for a given document without the need of having an API key.
\nIt allows users and systems to upload documents and receive a unique ID and URL without requiring authentication using an API key.
\nThe resulting ID and URL can then be accessed or shared through any channel.
\nWhen the URL is accessed by a Skribble user, the standard Skribble login/registration process occurs if not authenticated yet.
\nAfter the user confirms and claims the document, it will be moved from the upload area to the user's documents and processed as a normal uploaded document.
As initiator you can use the ID to track the document's status, download the final signed document, and delete it if needed.
\n","_postman_id":"37307cd8-11cf-4e54-a57b-4e1e96254ec7"},{"name":"Documents","item":[{"name":"Create","item":[{"name":"Simple PDF document upload","event":[{"listen":"test","script":{"id":"73dec0b2-e3a7-4859-a47c-de79309724de","exec":["let documentID = pm.response.json().id;","pm.environment.set(\"DOC_ID\", documentID);"],"type":"text/javascript","packages":{}}},{"listen":"prerequest","script":{"id":"d276b851-8bb5-4f41-a4bf-70bf1d655f4c","exec":[""],"type":"text/javascript","packages":{}}}],"id":"9cf195d0-bec5-4037-899d-1919b003b347","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"title\": \"Example contract PDF\",\r\n \"content\": \"{{BASE64_PDF}}\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v2/documents","description":"A simple PDF document upload using a Base64 encoded file as content.
The document upload or creation uses the same parameters as creating a SignatureRequest.
Actually, it is the other way around, a SignatureRequest uses /documents parameters.
The document content is either uploaded directly with the parameter combinations content and content_type or passed by URL in the parameter file_url. The server then downloads the content and takes the content type from the HTTP header.
Either the content or the file_url parameter can be used, but not both at the same time.
The caller is automatically assigned as the owner of the document and is solely authorized to assign further read and write permissions.
\n\n\n","_postman_id":"661d8c0f-7930-45f4-ae33-46b9ccbd17b5","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"411ae8c9-b158-4617-9a06-777a58b4e5a7","id":"411ae8c9-b158-4617-9a06-777a58b4e5a7","name":"Documents","type":"folder"}}},{"name":"Find","item":[{"name":"List all accessible documents","id":"97e9da9c-9f86-484a-89e3-b968394d334d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"GET","header":[],"url":"https://api.skribble.com/v2/documents","description":"Note
\n
All URLs passed to Skribble must use the HTTPS protocol.
The maximum document size is about 40 MB, which results in the maximum request size of 60 MB.
This request returns an array of all accessible Documents objects.
To query one single Documents object, you can pass the document ID {{DOC_ID}} with this request. The Documents object contains document metadata such as title, owner, size and useful page information.
Use this request to download a PDF document of a single Documents object identified by the document ID {{DOC_ID}}.
By default the PDF document is returned as raw bytes. By using the Header Accept=application/json the response will contain the base64 encoded PDF in the JSON body in the field content.
When uploading a PDF document to Skribble, the system generates some preview images for the PDF pages. These preview images can be requested by passing the page {{PAGE_ID}} you want to get a preview for, starting at 0 for page number 1.
\n\n","urlObject":{"protocol":"https","path":["v2","documents","{{DOC_ID}}","pages","{{PAGE_ID}}"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[{"id":"1dcb672e-9317-4a21-8c4d-65ced2229868","name":"Get the document page preview for page 0 with scale 20 (200)","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.skribble.com/v2/documents/{{DOC_ID}}/pages/0?scale=20","protocol":"https","host":["api","skribble","com"],"path":["v2","documents","{{DOC_ID}}","pages","0"],"query":[{"key":"scale","value":"20"}]}},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"image/webp or image/png ","description":"","type":"text","enabled":true}],"cookie":[],"responseTime":null,"body":"Image as raw bytes in WEBP format or PNG for older documemnts. See Content-Type."},{"id":"58151513-c9e7-4b5d-bc1e-4ef9f501187e","name":"Get the document page preview of page 0 with scale 100 (200)","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.skribble.com/v2/documents/{{DOC_ID}}/pages/0?scale=100","protocol":"https","host":["api","skribble","com"],"path":["v2","documents","{{DOC_ID}}","pages","0"],"query":[{"key":"scale","value":"100"}]}},"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"image/webp or image/png","description":"","type":"text","enabled":true}],"cookie":[],"responseTime":null,"body":"Image as raw bytes in WEBP format or PNG for older documemnts. See Content-Type."}],"_postman_id":"f168728b-dccb-4c6c-ad22-8120ab2cddff"}],"id":"aa128651-9c08-4281-8f90-d7e61abb8fc9","_postman_id":"aa128651-9c08-4281-8f90-d7e61abb8fc9","description":"","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"411ae8c9-b158-4617-9a06-777a58b4e5a7","id":"411ae8c9-b158-4617-9a06-777a58b4e5a7","name":"Documents","type":"folder"}}},{"name":"Modify","item":[{"name":"Delete the document","event":[{"listen":"test","script":{"exec":["pm.environment.set(\"AUTH_ACCESS_TOKEN\",\"\");","pm.environment.set(\"DOCUMENT_ID\",\"\");","pm.environment.set(\"SR_ID\",\"\");"],"type":"text/javascript","id":"53178f11-04ec-4082-8516-be1036446798"}}],"id":"294578e1-93f2-4d41-bc55-2850bfd7c4c1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"DELETE","header":[],"url":"https://api.skribble.com/v2/documents/{{DOC_ID}}","description":"By using the optional parameter
\nscaleyou can choose between a preview in real size usingscale=100or a thumbnail preview usingscale=20.
Deleting a Document is similar to deleting a SignatureRequest.
That means, deleting a Document does not necessarily remove the a Document from the system.
If there is MORE than one participant involved, then the DELETE request will only remove the current user from the Document.
Only when the lat user deletes the Document using the Skribble web application, the system will finally remove the object.
Updating a document is NOT allowed.
\nIf you want to make changes to a document, you need to provide a NEW document again.
\n","_postman_id":"a8110528-83f1-43c9-acae-566e120a9817","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"411ae8c9-b158-4617-9a06-777a58b4e5a7","id":"411ae8c9-b158-4617-9a06-777a58b4e5a7","name":"Documents","type":"folder"}}},{"name":"Object details","item":[],"id":"e4e5904a-6a6c-44ef-b49a-74b679b7d4df","description":"Beside the described examples, you can find all available fields to create or modify a SignatureRequest here in the detailed object descriptions.
\nWhen you request a Document object you will receive the following information within the object.
The Skribble API contains a /documents resource. Up until now it was used to download the signed content of a document.
The resource is used mainly by the /signature-requests resource in the background.
For an integrator there are only a few reasons to use the /documents resource:
a) You want to reuse a document in more than one SignatureRequest.
b) You want to modify the document before it is used in a SignatureRequest.
Currently there are no public modification options available.
Usually the starting point will be theSignatureRequest. See the chapter Reference > SignatureRequests for details.
The document content is not changeable, it is immutable. Any changes to the document's content always lead to a NEW document with a NEW ID.
\nThe ownership, as well as read and write access, are handed on from the parent to the child document.
\n\n\nReminder
\n
The document ID you receive after uploading will never be the same ID after signing, or any other change made to the document.
Documents are persisted only in an encrypted state. An individual AES-256 key is used for each document. The AES key itself is only accessible to the owner of a document and users with read or write permissions.
\nThe owner of a document and people with write permissions can manage read and write access. The owner can never be changed.
\nSkribble currently only supports PDF as a document format.
\nSince the PDF specification (ISO 32000-1:2008) is very extensive, we cannot guarantee that all PDF documents can be signed. Should you experience any issues with signing a PDF document, please get in touch with us. We will be happy to assist you.
\nSkribble also supports PDF/A documents according to ISO 19005-1:2005 from level PDF/A-1b.
The PDF/A document is usually still PDF/A-compliant even after the signature is made.
\n\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"2acddc84-ba6c-4476-8bb8-8fea6c644bf4"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"05df6303-9fec-42f6-b1bc-19827af9640f"}}],"_postman_id":"411ae8c9-b158-4617-9a06-777a58b4e5a7"},{"name":"User","item":[{"name":"Get signature qualities details for a user","id":"8de1cfa7-e5ed-423a-8c5d-40ba3efc5f2b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"GET","header":[],"url":"{{BASE_URL}}/v2/user/signature-qualities-detail?username=john.doe@skribble.com","description":"Caution Applying a visual signature may in some cases break some of the PDF/A rules!
\n
The result of this query will tell you what final signature quality will be used for the given user username to sign a document.
The resulting signature quality is determined in combination of the requested quality and legislation, whereas any stands for any legislation.
Description for the example request:
If you create a SignatureRequest with quality=AES_MINIMAL and the legislation=ZERTES the user in this example would finally sign the document with the signature quality QES.
As described in the previous chapter AES_MINIMAL will use QES as long as the user settings allow this.
We recommend using the signature-qualities-details endpoint to request detailed signature quality information for a user. This endpoint provides comprehensive data about the quality of the signature. However, for compatibility reasons, we continue to offer the previous endpoint, which delivers a simplified result set. This ensures that users of the older version of our API can still access essential signature quality information without needing to upgrade immediately.
The Skribble API provides the resource /user. This resource can be used to query user data. At the moment, only the endpoint /user/signature-qualities is offered to query the possible qualities a user can use for signing.
This endpoint provides detailled signature activities information for your business and your members within a specified date range.
Use these parameters to filter for a specific time range.
\nThe result set can be controlled using the optional pagination parameters page and size
The response contains the following information.
\nGeneral
\nActivities
\nUser
\n","urlObject":{"protocol":"https","path":["v2","activities","signatures"],"host":["api","skribble","com"],"query":[{"key":"start_date","value":"2024-01-01"},{"key":"end_date","value":"2024-01-31"},{"key":"page","value":"1"},{"key":"size","value":"50"}],"variable":[]}},"response":[{"id":"044cb2e5-cf10-44f1-804f-1b4011cb2dfe","name":"Get signature activities by business","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.skribble.com/v2/activities/signatures?start_date=2024-01-01&end_date=2024-01-31&page=1&size=50","protocol":"https","host":["api","skribble","com"],"path":["v2","activities","signatures"],"query":[{"key":"start_date","value":"2024-01-01"},{"key":"end_date","value":"2024-01-31"},{"key":"page","value":"1"},{"key":"size","value":"50"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text","enabled":true}],"cookie":[],"responseTime":null,"body":"{\n \"total_pages\": 1,\n \"total_items\": 2,\n \"current_page\": 1,\n \"size\": 50,\n \"activities\": [\n {\n \"_id\": \"9988554433221100aabbccdd\",\n \"action\": \"SIGNED\",\n \"timestamp\": \"2024-01-10T10:10:10.000Z\",\n \"signature_request_id\": \"88552233-0123-1234-1234-0123456789ab\",\n \"cost_center\": \"Department A\",\n \"initiator\": {\n \"email\": \"johnny@skribble.com\",\n \"first_name\": \"Johnny\",\n \"last_name\": \"Doe\",\n \"type\": \"member\",\n \"mobile\": \"419988776655\"\n },\n \"signer\": {\n \"email\": \"johnny.doe@skribble.com\",\n \"first_name\": \"Johnny\",\n \"last_name\": \"Doe\",\n \"type\": \"member\",\n \"mobile\": \"419988776655\"\n }\n },\n {\n \"_id\": \"aa88554433221100aabbccee\",\n \"action\": \"SIGNED\",\n \"timestamp\": \"2024-10-01T10:10:10.000Z\",\n \"signature_request_id\": \"33221144-1234-1234-1234-aabbccddeeff\",\n \"cost_center\": \"Department B\",\n \"initiator\": {\n \"email\": \"jane.doe@skribble.com\",\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"type\": \"member\",\n \"mobile\": \"49112233445566\"\n },\n \"signer\": {\n \"email\": \"johnny.doe@skribble.com\",\n \"first_name\": \"Johnny\",\n \"last_name\": \"Doe\",\n \"type\": \"member\",\n \"mobile\": \"419988776655\"\n }\n }\n}"}],"_postman_id":"f2f445ee-c62b-4b0f-99ab-63ea72c2ba16"}],"id":"c76302b4-27b4-4806-a0fb-8c414007bb84","description":"Activities provide detailled signature usage information for your business.
\n","_postman_id":"c76302b4-27b4-4806-a0fb-8c414007bb84"},{"name":"Errors","item":[],"id":"9ad80a27-749d-4798-9a32-f6c885f03777","description":"The Skribble API uses the following HTTP error codes
\n","_postman_id":"9ad80a27-749d-4798-9a32-f6c885f03777"}],"id":"cc73aec6-a77e-4938-b6c6-ddcf58de6fc1","description":"The reference gives you an overview about the objects and functions provided by the Skribble API. The individual reference chapters are not sorted alphabetically but according to the probability of their use.
\n","_postman_id":"cc73aec6-a77e-4938-b6c6-ddcf58de6fc1"},{"name":"๐ Monitoring","item":[{"name":"Callbacks","item":[{"name":"Create a signature request with all possible callbacks","event":[{"listen":"test","script":{"exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","id":"9d1c8c7c-5003-4518-a1b4-2d0b57e1b8b9"}}],"id":"9e3c7c20-0745-4fa1-8a97-eca158aaf3dc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":""},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"content\": \"{{BASE64_PDF}}\",\n \"signatures\": [\n {\n \"account_email\": \"john.doe@skribble.com\"\n }\n ],\n \"callback_success_url\": \"https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/success?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678\",\n \"callback_update_url\": \"https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/update?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678\",\n \"callback_error_url\": \"https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/error?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678\"\n}"},"url":"https://api.skribble.com/v2/signature-requests","description":"In this example we create a SignatureRequest for one signer. We add the fields callback_success_url, callback_update_url and callback_error_url. Every change on the resulting SignatureRequest will trigger a POST request to one of the given callback urls.
In certain scenarios, it is beneficial to view and verify the status of callbacks for a SignatureRequest. For example, you might want to confirm whether a callback has already been executed or to identify any errors that occurred during the callback process.
This endpoint provides the capability to obtain detailed information about the callbacks associated with a SignatureRequest, enabling comprehensive monitoring and troubleshooting. By using this endpoint, you can ensure the reliability and accuracy of your callback operations and quickly address any issues that may arise.
Result
\nIf no callback has been called yet, the response will be an empty array. Otherwise it will contain an array of callback objects that were already executed.
The fields description of the single callback object:
\n","urlObject":{"protocol":"https","path":["v2","signature-requests","{{SR_ID}}","callbacks"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[{"id":"0403a10d-a96a-4c31-aa7a-0fd4645887af","name":"Get the list of callbacks for a signature request","originalRequest":{"method":"GET","header":[],"url":"https://api.skribble.com/v2//signature-requests/{{SR_ID}}/callbacks"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"[\n {\n \"signature_request_id\": \"cccccccc-5555-8888-abab-123456789012\",\n \"type\": \"UPDATE\",\n \"state\": \"OPEN\",\n \"url\": \"https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/update?document_id=123654789_ID&token=12345678\",\n \"attempts\": 1,\n \"messages\": [\n \"Failed: 404 - 404 Not Found: token not found\"\n ],\n \"created_at\": \"2049-01-01T10:00:00.000Z\",\n \"updated_at\": \"2049-01-01T10:00:30.000Z\"\n }\n]"}],"_postman_id":"c74befb3-5fbd-42ec-b23b-107faf7d0a74"}],"id":"4c36590d-e3c2-4d52-beca-8ceb11f7e059","description":"The easiest way to get the correct document ID after signing, is to use success, update and failure callbacks. These callbacks are triggered as soon as one of the mentioned events takes place.
\nTo use these callbacks, the corresponding URL that should be called on one of the events, can be added to the SignatureRequest in one of these fields
\n\n๐ก Good to know
\n
Callback URLs will be called using a POST request.
Callback URLs will be HTML encoded for the request. So please ensure, that your URL does not contain already encoded characters.
The callback URLs may contain placeholders, which are replaced with the current SignatureRequest data before the URL is called.
So, if the success callback triggers, the URL contains the correct document ID, which can then be used to retrieve the document.
\nCallbacks support TLS mutual authentication (mTLS). If the callback endpoint (your side) asks for a client authentication during the TLS handshake, Skribble will authenticate itself with a X.509 certificate for api.skribble.com.
The callback will additionally send the related root certificate from Globalsign as certificate authority as well as the related intermediate certificate by Alpha SSL as certificate provider.
Default: If a callback does not respond immediately, e.g. due to a system downtime on the callback url server (your side), Skribble will retry to call to the callback url every 10 minutes for two hours. After this, Skribble will stop its efforts to contact the callback endpoint.
\nRetry-After: A callback response may contains a Retry-After header. With this value your system does informs Skribble API to pause retry attempts calling the callback URL until this pause time in seconds expires.
While polling the SignatureRequests to check their status is a valid approach, it does come with some drawbacks. As a result, we highly recommend utilizing callbacks instead. Here are the reasons why callbacks are preferable:
However, if callbacks are not feasible for your situation and you must resort to polling, please keep the following considerations in mind:
\nBy following these guidelines, you can optimize the polling approach while ensuring compliance with the Skribble API rate limits and maintaining a balanced usage of system resources.
\n","_postman_id":"1bb2c62e-feaf-4fbe-b434-6bbc5211cfef"},{"name":"Rate limits","item":[],"id":"15d2084d-43f3-4900-9a96-64e33211cc0c","description":"The Skribble API enforces the following rate limits:
\nThese rate limits ensure fair usage and efficient resource allocation for Skribble API interactions.
\nWhen the rate limit is reached, the API will respond with an HTTP error code 429 (Too Many Requests)
If you need to monitor the responsiveness of the Skribble API, you may want to have a look at the health resource. It will give you a short update about the current status of the system. status:UP tells you that the system is up and running.
Skribble offers two ways to monitor the status of a SignatureRequest. Callbacks and Polling on the SignatureRequest.
Whenever possible, we recommend using the callbacks, since it has economic and ecological advantages.
This is a base64 encoded one page PDF, ready to be used in the Skribble API Quickstart examples.
Please copy this directly into your requests or add an environment variable for this.
This is a base64 encoded PNG image (size = 200 x 55 pixel). It is ready to be used in the Skribble API Quickstart examples.
Please copy this directly into your requests or add an environment variable for this.
Please note that the Skribble General Terms and Conditions apply when using the Skribble API.
\nIf you have any questions or notice any errors, drop us a message at support@skribble.com
\nThank you for using Skribble and happy signing.
\n","_postman_id":"ec321c8a-f7d5-4949-b597-e6dfc1b62749"}],"event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"26cee453-09de-417e-8360-85015c18977e"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"69cc3415-bd8a-4cad-9de3-ae2319668776"}}],"variable":[{"key":"AUTH_ACCESS_TOKEN","value":""}]}