The Skribble API v1 documentation describes the public available Skribble API v1.
\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 Setting up Skribble Business.
\nThis documentation describes the version of Skribble API v1
\nThe base URL of version 1 is https://api.skribble.com/v1
\nThe latest version of the Skribble API is Skribble API v2.
\nThe Skribble API v2 was officially released at 25.06.2024
\nThe Skribble API v2 is the latest version of our API.
\nIf you are looking for Skribble API v2 documentation please visit https://api-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.
\nTo 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":["v1","access","login"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[{"id":"70861f26-1d1b-411e-917b-fc95e170293c","name":"Alternative login as user \"api_demo_your_name\" - x-www-form-urlencoded (200)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/x-www-form-urlencoded","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/v1/access/login"},"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJWlMxY0pXQXlXVFdZeDR6dXRGNzJlYWVILTA0MUprTDF5N2Z3aXA1T3UwIn0Ei3Hm3rhjOAq5dWo6Z0l6bzvyGCXd87oRoOWDM2sW4KErCKYmcQ6ks8FVj3Fn8wXNIVAnp5ClZvWNw9Uks1zM9P2IXBbBPn7DIQGvM ..."},{"id":"21ca5d65-25c3-4eb6-a2c7-e97e5fb2b7bd","name":"Login user api_demo_user_name (200)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","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/v1/access/login"},"status":"OK","code":200,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJWlMxY0pXQXlXVFdZeDR6dXRGNzJlYWVILTA0MUprTDF5N2Z3aXA1T3UwIn0Ei3Hm3rhjOAq5dWo6Z0l6bzvyGCXd87oRoOWDM2sW4KErCKYmcQ6ks8FVj3Fn8wXNIVAnp5ClZvWNw9Uks1zM9P2IXBbBPn7DIQGvM ..."},{"id":"f3ec0d96-c095-4da9-b46a-d6ba4a0818ab","name":"Login user api_demo_user_name (400)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","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/v1/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":"c1ce2789-9407-4816-9719-9426b6f58240"}],"id":"7f7391c5-bac9-4f37-94b9-bcd22814f053","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 usually starts 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
support@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":"5f711b3e-69d8-4ebb-9e8d-92fd513f8d79","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"08ac076d-4639-4478-8098-2465157eaa1d","id":"08ac076d-4639-4478-8098-2465157eaa1d","name":"π Quickstart","type":"folder"}}},{"name":"1. Create a SignatureRequest","item":[{"name":"Create a simple signature request for a PDF document","event":[{"listen":"test","script":{"exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","id":"efc8497c-2b92-4704-bf38-e763c34a3667"}}],"id":"b7a8e421-6d43-4362-bcdf-fbddad2a9876","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"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\"signer_email_address\" : \"you@example.info\"\n },\n {\n\t\t\t\"signer_email_address\" : \"personOneToSign@external.net\"\n },\n {\n\t\t\t\"signer_email_address\" : \"personTwoToSign@external.net\"\n } \n ]\n}"},"url":"https://api.skribble.com/v1/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.
\ntitle should be short and treated like a file name. This field is mandatory.signatures array contains all signers of the document.signer_email_address 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.content field contains the Base64 encoded bytes of the PDF document.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.\"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":"c8db881b-6dae-4125-9535-95866e9cedf8","id":"c8db881b-6dae-4125-9535-95866e9cedf8","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":"05e291cb-596f-470e-a07a-e57577a99c24","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":"900a3e6b-83b9-4124-95a8-de372b853e77","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":"1c0ca6e0-e33b-4000-b279-a0da580b60d4","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":"b1d8b87b-ad84-4e6c-a4f5-6b88d63df5ae"}],"id":"c8db881b-6dae-4125-9535-95866e9cedf8","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 would 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.
\nUsing 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.
However, for usability reasons the duration cannot be shorter than 10 seconds or longer than 90 seconds. If values outside this range are given the actual timeout will be enforced to stay within the min and max.
\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":"c4349357-8f9d-4051-a5cd-0918b7063f60"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"dc52ee1b-e700-43da-b984-fd841dc9beb6"}}],"_postman_id":"c8db881b-6dae-4125-9535-95866e9cedf8"},{"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":"7a626f7f-4cc0-4af5-9a7f-4cb2b296b293"}}],"id":"35728f2a-a017-4d87-920b-cd91f947b460","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.skribble.com/v1/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 /v1/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 /v1/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:
\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":["v1","signature-requests"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[{"id":"608e4e82-5996-4956-b6d5-03cb78097bd5","name":"Create a signature request without inital signers (200)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"message\": \"Please sign this document!\",\n \"content\": \"{{BASE64_PDF}}\",\n \"write_access\" : [\"john.doe@skribble.com\"]\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v1/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":"bbd5e882-60cb-4b87-a2c0-80f52cf50e36"}],"id":"01fee517-929a-44d0-bd5d-576702cfd083","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.
\nPDF 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":["v1","signature-requests"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"7b81161a-1f73-466b-a0a5-33e5a612d903"},{"name":"Positioning signature fields on a document","event":[{"listen":"test","script":{"exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","id":"179c4f13-41aa-4fca-ad4f-d5a9d9b505ce"}}],"id":"0620f576-f592-4ca2-ac53-30286f01830d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"message\": \"Please sign this document!\",\n \"content\": \"{{BASE64_PDF}}\",\n \"signatures\" : [\n {\n \"signer_email_address\" : \"john.doe@skribble.com\",\n \"visual_signature\" : {\n \"position\" : {\n \"x\" : 120,\n \"y\" : 60,\n \"width\" : 300,\n \"height\": 120,\n \"page\" : \"0\"\n }\n }\n },\n {\n \"signer_email_address\" : \"karen.smith@skribble.com\",\n \"visual_signature\" : {\n \"position\" : {\n \"x\" : 420,\n \"y\" : 60,\n \"width\" : 300,\n \"height\": 120,\n \"page\" : \"4\"\n }\n }\n }\n ]\n}"},"url":"https://api.skribble.com/v1/signature-requests","description":"It is possible to specify exactly the position of the visual signature in a document.
\nThe Skribble web application will enforce the usage of the predefined position.
\nIn the background, Skribble will create a Acroform signature field on this position and place the signature in the new field.
\nIn the example, John Doe's signature will be visible in the lower-left corner on page 1. Karen Smith's signature will only be visible on page 5.
\nThe origin of the coordinate system is at the bottom left corner of the page and the x and y coordinates of the visual signature specify the location of the bottom left corner of the visual signature. All units are in pixels.
\n\n\n","urlObject":{"protocol":"https","path":["v1","signature-requests"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"0620f576-f592-4ca2-ac53-30286f01830d"}],"id":"e5e3e412-da66-4f44-8441-5c9dbdfbd888","description":"Note
\n
The visual signature information is distinct to each signer, so you can mix them if necessary.
The visual signature on a PDF document serves as an optional element and doesn't affect the legal weight of the electronic signature. It is up to a signer to decide whether to add the visual signature to a document in addition to the electronic signature or not.
\nAdding the visual signature to a document helps to keep the look and feel of the handwritten signature and provide additional information about the signer.
\nIf a signature request doesn't contain any visual signature instructions, it is up to the user to create a visual signature and place it anywhere on the document when using the
Skribble web application.
This matches how the physical world handles placement information. The document CAN contain visual hints, Please sign here, but they are not mandatory.
\nIn the digital world, we have some more options.
\n","_postman_id":"e5e3e412-da66-4f44-8441-5c9dbdfbd888"},{"name":"Provide PDF file to sign","item":[{"name":"Create a signature request including a document upload","event":[{"listen":"test","script":{"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","id":"2ca96a5d-8380-4606-b3c3-49d4ec15de46"}}],"id":"bf4f68b8-24a4-4c7e-a7af-adced1a95376","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"signatures\": [\n {\n \"signer_email_address\" : \"john.doe@skribble.com\"\n }\n ],\n \"content\" : \"{{BASE64_PDF}}\" \n}"},"url":"https://api.skribble.com/v1/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":["v1","signature-requests"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[{"id":"0a211b9f-7fd0-4d58-a351-ad6043a14b1e","name":"Create signature request with a document reference (200)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"signatures\": [\n {\n \"signer_email_address\": \"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/v1/signature-requests"},"_postman_previewlanguage":"Text","header":[],"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":"4d632c09-5d68-4d60-9edd-dd98ade5c5cf"},{"name":"Create a signature request for an uplaoded document","event":[{"listen":"test","script":{"exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","id":"bd030b78-cbc3-413d-86da-6704dccbaa94"}}],"id":"80071f05-84a6-4faa-8e50-65899073329a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"signatures\": [\n {\n \"signer_email_address\": \"john.doe@skribble.com\"\n }\n ],\n \"document_id\": \"{{DOC_ID}}\"\n}"},"url":"https://api.skribble.com/v1/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 Documents.\nSo, 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":["v1","signature-requests"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[{"id":"82c5b04f-09f8-498c-9311-6bbbda849366","name":"Create signature request for uploaded document (200)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"signatures\": [\n {\n \"signer_email_address\": \"john.doe@skribble.com\"\n }\n ],\n \"document_id\": \"{{DOC_ID}}\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v1/signature-requests"},"_postman_previewlanguage":"Text","header":[],"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":"80071f05-84a6-4faa-8e50-65899073329a"}],"id":"eafeceed-ad0c-4f93-9e23-dc2ffd00ab3d","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":"eafeceed-ad0c-4f93-9e23-dc2ffd00ab3d"},{"name":"Define the signature quality and legislation","item":[{"name":"Create a signature request with quality and legislation","event":[{"listen":"test","script":{"exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","id":"b9da970e-2a0e-4477-add8-c029084bfdfb"}}],"id":"5b846df5-1aaa-4ef9-9755-c4992839e175","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"title\": \"Create test SigntureRequest\",\n \"signatures\": [\n {\n \"signer_email_address\": \"john.doe@skribble.com\"\n }\n ],\n \"content\": \"{{BASE64_PDF}}\",\n \"quality\": \"AES\",\n \"legislation\": \"ZERTES\"\n}"},"url":"https://api.skribble.com/v1/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":"01a8883f-7dad-4b22-8628-4586ffc4da91"},{"name":"Signing without an account","item":[{"name":"Create a signature request for a \"no account signer\"","event":[{"listen":"test","script":{"exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","id":"271306b9-9a1a-4968-bd76-ec944a9ad157"}}],"id":"9ec8ceab-8b7a-4bc3-9c5d-585ae446725e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"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 }"},"url":"https://api.skribble.com/v1/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.
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_idendity_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_idendity_data and signer_email_address 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_idendity_data will be invited to sign.
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":"0b690074-6801-4257-8c05-89f16a100baa"},{"name":"Disable notification e-mails","item":[{"name":"Create a signature request and disable e-mail notifications for one signer","event":[{"listen":"test","script":{"exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","id":"297bf5fd-bd48-4bb0-9ec4-1ed421c0741c"}}],"id":"33395fae-f4f5-48cb-9c1e-3fc74e991f8b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"content\": \"{{BASE64_PDF}}\",\n \"signatures\": [\n {\n \"signer_email_address\": \"john.doe@skribble.com\"\n },\n {\n \"signer_email_address\": \"charles.doe@skribble.com\",\n \"notify\": false\n }\n ]\n}"},"url":"https://api.skribble.com/v1/signature-requests","description":"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":["v1","signature-requests"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"33395fae-f4f5-48cb-9c1e-3fc74e991f8b"}],"id":"8bd9ac4c-ae35-41c5-9fc3-998cacab08b4","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.
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":"727fd651-41b8-4a1d-86b7-adb49dada670"},{"name":"Define automatic attachments","item":[{"name":"Create a signature request and define automatic attachments","event":[{"listen":"test","script":{"exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","id":"a1a37852-4ffb-4e57-aa8c-664fe05cc483"}}],"id":"41dcfa6f-c285-4c50-ba82-01d0a2fb4dda","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"content\": \"{{BASE64_PDF}}\",\n \"attach_on_success\": [\"SIGNED_DOCUMENT\", \"SIGNATURE_PROTOCOL\"],\n \"signatures\": [\n {\n \"signer_email_address\": \"john.doe@skribble.com\"\n }\n ]\n}"},"url":"https://api.skribble.com/v1/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.
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 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\n","urlObject":{"protocol":"https","path":["v1","signature-requests"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[{"id":"1558c095-29bb-4444-80c1-3447dff7807f","name":"List SignatureRequests with john.doe@skribble.com as signer","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.skribble.com/v1/signature-requests?signer_email_address=john.doe@skribble.com","protocol":"https","host":["api","skribble","com"],"path":["v1","signature-requests"],"query":[{"key":"signer_email_address","value":"john.doe@skribble.com"}]}},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"[\r\n {\r\n \"id\": \"56c40808-ab69-4b50-c174-a0d59d59c48d\",\r\n \"title\": \"First example contract\",\r\n \"signatures\": [\r\n {\r\n \"sid\": \"e4c5b108-cdab-938a-aed9-ebabbc92a013\",\r\n \"signer_email_address\": \"john.doe@skribble.com\",\r\n ...\r\n }\r\n ],\r\n ...\r\n },\r\n {\r\n \"id\": \"c9cce9be-4a6a-0000-a42e-6ea4172a378b\",\r\n \"title\": \"Second example contract\",\r\n \"signatures\": [\r\n {\r\n \"sid\": \"fa84e5bd-cdab-938a-aed9-ebabbc92a013\",\r\n \"signer_email_address\": \"john.doe@skribble.com\",\r\n ...\r\n }\r\n ] \r\n ...\r\n },\r\n {\r\n \"id\": \"3485e7c5-4a6a-ffff-a42e-6ea4172a378b\",\r\n \"title\": \"Third example contract\",\r\n \"signatures\": [\r\n {\r\n \"sid\": \"e4c5b108-cdab-938a-aed9-ebabbc92a013\",\r\n \"signer_email_address\": \"john.doe@skribble.com\",\r\n ...\r\n }\r\n ],\r\n ...\r\n },\r\n ...\r\n}"},{"id":"bccd64ba-c869-4bd6-9a46-a2f94b31c0e6","name":"List all accessible SignatureRequests","originalRequest":{"method":"GET","header":[],"url":"https://api.skribble.com/v1/signature-requests"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"[\r\n {\r\n \"id\": \"56c40808-ab69-4b50-c174-a0d59d59c48d\",\r\n \"title\": \"First example contract\",\r\n ...\r\n },\r\n {\r\n \"id\": \"c9cce9be-4a6a-a958-a42e-6ea4172a378b\",\r\n \"title\": \"Second example contract\"\r\n ...\r\n },\r\n {\r\n \"id\": \"c9cce9be-4a6a-a958-a42e-6ea4172a378b\",\r\n \"title\": \"Third example contract\"\r\n ...\r\n },\r\n ...\r\n}"},{"id":"e6ed30c0-79c6-432f-be6a-d3e83f90d84c","name":"List SignatureRequests with status DECLINED","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.skribble.com/v1/signature-requests?status_overall=DECLINED","protocol":"https","host":["api","skribble","com"],"path":["v1","signature-requests"],"query":[{"key":"status_overall","value":"DECLINED"}]}},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"[\r\n {\r\n \"id\": \"56c40808-ab69-4b50-c174-a0d59d59c48d\",\r\n \"title\": \"First example contract\",\r\n \"status_overall\": \"DECLINED\",\r\n ...\r\n },\r\n {\r\n \"id\": \"cccccccc-4a6a-a958-a42e-6ea4172a378b\",\r\n \"title\": \"Nth example contract\",\r\n \"status_overall\": \"DECLINED\",\r\n ...\r\n }\r\n}"}],"_postman_id":"d54cfdd8-a025-4394-9f09-85d61ac248dc"},{"name":"Get a single SignatureRequest","id":"c7c711be-e20d-4498-9953-526c60a183b5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.skribble.com/v1/signature-requests/{{SR_ID}}","description":"Note
\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 signer_email_address=john.doe@skribble.com will only find aSignatureRequestswhere the fieldsigner_email_addressis exactly john.doe@skribble.com. It won't find another.john.doe@skribble.com
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":"5753d5ab-57bf-4871-9642-b1e2f69b55e2"},{"name":"Modify","item":[{"name":"Add or remove signers to/from a signature request","id":"055c7265-e3a9-47e3-baf3-255201a84a46","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"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 \"signer_email_address\": \"john.doe@skribble.com\"\r\n },\r\n {\r\n \"signer_email_address\": \"new.signer@skribble.com.org\"\r\n }\r\n ]\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.skribble.com/v1/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 a signer to the SignatureRequest simply add a new entry to the signatures array.
To remove a signer from the SignatureRequest simply remove the signature entry the signatures array.
\n\nImportant
\n
signatures array any more will be removed!signatures can only be made as long as none of the signers has already completed the signature.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.
Modifications on existing SignatureRequests should be handled with care.
We recommend creating the SignatureRequests with all necessary information.
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.
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":"208d1f90-55be-4485-b33c-fd9ed2136621"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"ffd07862-0cc1-45b6-9d13-47aea63144f4"}}],"_postman_id":"4b87240e-d34e-4bb3-a989-c6757f4ea164"},{"name":"Seal","item":[{"name":"Create","item":[{"name":"Seal a document","event":[{"listen":"test","script":{"exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","id":"997adbb4-d083-4d2d-9a0d-dc25b9822b35"}}],"id":"969549f9-4abb-40e2-8ba5-f19b7dcd1a74","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"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}"},"url":"https://api.skribble.com/v1/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":["v1","seal"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[{"id":"92e3c263-717e-4095-9a23-799c330e3c45","name":"Seal a document (200)","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","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/v1/seal"},"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"{\n \"document_id\": \"e4cde459-6e63-0095-10b8-55b39ec39f46\"\n}"}],"_postman_id":"969549f9-4abb-40e2-8ba5-f19b7dcd1a74"},{"name":"Seal a document with a specific seal","event":[{"listen":"test","script":{"exec":["let srID = pm.response.json().id;","pm.environment.set(\"SR_ID\", srID);",""],"type":"text/javascript","id":"8b69b392-50a6-4d29-862d-61bf82d845bf"}}],"id":"4fa31bb4-7b21-4d94-a652-e1b5854c74c9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"content\": \"{{BASE64_PDF}}\",\n \"account_name\": \"ais_company_seal_some_department\"\n}"},"url":"https://api.skribble.com/v1/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 /v1/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 /v1/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. \nWith 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 contact us at support@skribble.com.
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":"5e09b281-0576-4dc4-a14e-9e678b6a102c","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"604f5e3c-50c2-4ded-88ef-c209904ebd60","id":"604f5e3c-50c2-4ded-88ef-c209904ebd60","name":"Documents","type":"folder"}}},{"name":"Find","item":[{"name":"List all accessible documents","id":"78a4ea03-b08f-44ef-a78e-0300a9a02af5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.skribble.com/v1/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":["v1","documents","{{DOC_ID}}","pages","{{PAGE_ID}}"],"host":["api","skribble","com"],"query":[],"variable":[]}},"response":[{"id":"2875ee6a-60b3-4347-98c6-462e56b5f81a","name":"Get the document page preview for page 0 with scale 20 (200)","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.skribble.com/v1/documents/{{DOC_ID}}/pages/0?scale=20","protocol":"https","host":["api","skribble","com"],"path":["v1","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":"a6ad6409-3c8d-4698-9a64-520394703cff","name":"Get the document page preview of page 0 with scale 100 (200)","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.skribble.com/v1/documents/{{DOC_ID}}/pages/0?scale=100","protocol":"https","host":["api","skribble","com"],"path":["v1","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":"328af4d5-a140-495a-afcc-dd2b3992b6c3"}],"id":"525e8327-b56a-4f7c-ad93-af7143879795","_postman_id":"525e8327-b56a-4f7c-ad93-af7143879795","description":"","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"604f5e3c-50c2-4ded-88ef-c209904ebd60","id":"604f5e3c-50c2-4ded-88ef-c209904ebd60","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":"3e8b1ba2-f92e-451b-9ac9-7fc8d68d2b5a"}}],"id":"329ada26-b486-49ef-800e-8b0e1b0bfef8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"DELETE","header":[],"url":"https://api.skribble.com/v1/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":"a3e3f0cb-382b-439d-bed0-fec256566ed1","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"604f5e3c-50c2-4ded-88ef-c209904ebd60","id":"604f5e3c-50c2-4ded-88ef-c209904ebd60","name":"Documents","type":"folder"}}},{"name":"Object details","item":[],"id":"ac415e4c-ce0d-4016-a0af-6a27bd8dd1b9","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.
The only supported modification right now is adding a watermark to the document.
Usually the starting point will be the \nSignatureRequest. See the chapter 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\nThe document ID you receive after uploading will never be the same ID after signing, or any other change made to the document.
\n
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. \nThe PDF/A document is usually still PDF/A-compliant even after the signature is made.
\n\n\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"9f45b2ce-d143-4fb0-9cdf-5573850894b1"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"1277c456-ecda-402f-aeb4-14d762404da5"}}],"_postman_id":"604f5e3c-50c2-4ded-88ef-c209904ebd60"},{"name":"User","item":[{"name":"Get a user's signature qualities","id":"8e1150e1-1292-420a-8fde-7aefe4d50e2e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.skribble.com/v1/user/signature-qualities?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. \nThe resulting signature quality is determined in combination of the requested quality and legislation, whereas any stands for any legislation.
Description for the example request:
\nIf 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.
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.
The Skribble API uses the following HTTP error codes
\n","_postman_id":"2b16fb8d-b832-40e5-93de-fc7362e539e7"},{"name":"Discontinued","item":[{"name":"NoAccountBatchSignatureRequest","item":[],"id":"77327cb3-f565-455e-b255-131a831dffc3","description":"\n\n","_postman_id":"77327cb3-f565-455e-b255-131a831dffc3"}],"id":"46a640ab-6de6-454f-8728-ac6db8ea696a","_postman_id":"46a640ab-6de6-454f-8728-ac6db8ea696a","description":""}],"id":"7cf7bbaf-8006-4141-b97f-9762456e44fd","description":"The feature of using No Account Batch Signature Request is no longer provided.
\n
It is discontinued as of 03rd July 2023. It will no longer be supported for business reasons.
The feature has not been actively used by any of our customers over the past nine month prior to its discontinuation.
The reference gives you an overview about the objects and functions provided by the Skribble API.
\n","_postman_id":"7cf7bbaf-8006-4141-b97f-9762456e44fd"},{"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":"2c69e3ca-4f42-4c0c-9679-154bbe48cee5"}}],"id":"b5443375-5c8c-4570-9674-a5e1193acea3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"title\": \"Example contract\",\n \"content\": \"{{BASE64_PDF}}\",\n \"signatures\": [\n {\n \"signer_email_address\": \"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/v1/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.
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\nNotes
\n
\n\nCallback URLs will be called using a POST request.
\n
\n\nCallback URLs will be HTML encoded for the request. So please ensure, that your URL does not contain already encoded characters.
\n
\n\nAlthough Skribble does not limit the size of the URL, any limitations on the customer's proxies and web servers may apply.
\n
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.
\n\n\nNote
\n
Callbacks 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":"f84f07e7-cb65-447c-987d-72d65b8a83f5"},{"name":"Rate limits","item":[],"id":"8e0a5a91-7c29-47d5-8bcc-188148612028","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":"501e5053-da91-4ff1-a2aa-36d1b2f782d6"}],"event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"c4e88161-e742-462e-8594-ff45960f355e"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"ffab310b-b6c1-4e0b-9693-a4b2fdb6343e"}}],"variable":[{"key":"AUTH_ACCESS_TOKEN","value":""}]}