Tutorial : How to generate e-signature requests with API

In this tutorial we will use the Woleet API to generate an e-signature workflow. The goal is to get an external signatory to sign a document and have the proof of this signature anchored in the Bitcoin blockchain.

Let’s say you have a document, any kind of document. It could be a PDF, a MP3, a 3D model or any kind of digital content. The starting point should be a file.

In the end you want someone to digitally sign this document. With Woleet there is 3 ways someone can sign a document : 

• using digital signature delegation : here woleet generate a key pair and associate it with signatory identity. Digital signature is done by the user by using email and OTP SMS validation
• using an external (possibly your own) identity server. The Woleet Identity Server’s role is to assign keys to identities and manage their lifecycle (creation, deletion, revocation). The Woleet ID server is also used for signature verification as it will the one knowin ang an proving signatories’ identities.
• using his own keys : with Woleet it’s possible for the user to sign with key pairs in its own control. This is done using either a Ledger Nano S or the Woleet ID Mobile  application (which is basically a wallet protecting one’s own keys).

In order to create a signature with API you’ll need : 

In this example we will create a simple signature request with only one signatory. It’s possible to have as many signatories you want. Note that one signature credit will be used for each signature. If you have a document with 10 signatories you will use 10 signatures credits each time a signature is completed.

• The file you want them to sign
• the signatory common name (firstname  and lastname)
• the signatory email
• the signatory phone number
• A Woleet subscription with signature credits. We strongly recommend to do this on the sandbox environment accessible from Business plan only.

Step 1 – Calculating file hash

Woleet e-signature works from files hashes only. You don’t need to upload the document anywhere so you can keep it completely confidential. Note that in order to complete the signature process, the signatory will need the same document. 

Here we will use openssl to calculate file’s hash using SHA256 algorithm : 

>openssl dgst -sha256 test.pdf 

>SHA256(test.pdf)= 6a8a74bda899c6c90add84362c3d7dde95adf643fcdfcc023e7dad1f06c9d4dc

Step 2 – Creating the request 

In order to use the Woleet API you’ll need an API. To get your key, sign in on ProofDesk and go to your user preferences to generate a new one, if you had not already.

When you have your API key you can build the API call following the signature request documentation. Check it here

curl 'https://api.woleet.io/v1/signatureRequest' 

-X POST --header 'Content-Type: application/json' 

--header 'Accept: application/json' --header 'authorization: Bearer [API_TOKEN]' 

-d '

{

"name": "[REQUEST_NAME]",

"hashToSign":"[FILE_HASH]",

"authorizedSignees":

 
   [{"commonName":"[SIGNATORY_COMMON_NAME]",

   "email":"[SIGNATORY_EMAIL]",

    "requiresOTP":true,

    "countryCallingCode":"[SIGNATORY_PHONE_COUNTRY_CODE]",

    "phone":"[SIGNATORY_PHONE_NUMBER]"}]

}'

Here are some explanations about the parameters used in this request made with curl :

• [API_TOKEN] is your own API token used for authentication
• [REQUEST_NAME] is the name of the signature request. This name identifies the request and can be anything, it could be fore example “Test.pdf request”
• [FILE_HASH] is the SHA256 hash of the target document 
• [SIGNATORY_COMMON_NAME] is the name identifying the signatory, usually first name last name, but you can actually use any string e.g: “John Doe”
• [SIGNATORY_EMAIL] is the signatory’s email
• [SIGNATORY_PHONE_COUNTRY_CODE] is the mandatory country code of the signatory mobile phone number e.g.: 33 for France 
• [SIGNATORY_PHONE_NUMBER] is the signatory phone number e.g.: 612345678 

As long as the API call is done, an email is sent automatically to the signatory. The email will look like this : 

The recipient of that email will need to complete the signature. By clicking on the “Sign” green button he will end on a web page like this

This tutorial is voluntarily simple in order to help you learning our API quick. It describes a minimal configuration workflow but it’s important to note that you can build much more complex things with the API and create your own signature workflow exactly how you want it. You can change the notifications you want to send to signatories, emails look and feel so it could fit your own branding, you can even build your own signature page and many other things!

If you want to go further, go and check our advanced e-signature customization capabilities in our documentation here 

---