Ask for signature

👍

Too busy to read the documentation?

You will find here very simple curl and shell code samples demonstrating the basic usage of the Woleet API.

To ask a set of signers to sign a file, you simply need to ask the Woleet API to create a signature request.

A signature request manages the full life cycle of the signature workflow:
👉 send signature invitation emails to signers
👉 redirect signers to the signature page
👉 authenticate signers on the signature page
👉 register signatures
👉 build all the pieces of evidence required to verify the signatures:

• the audit trail (list of all events that occurred during the signature workflow)
• a proof of seal of the audit trail by Woleet
• a proof of signature for each signer
  👉 send all the pieces of evidence to the requester and the signers (attached to a human readable signature attestation PDF document)

First of all, you need to compute the SHA256 hash of the file to sign (its 'digital fingerprint').

Let's do it using a simple shell command using openssl to do the computation:

$ cat <your file> | openssl dgst -sha256 |  cut -d " " -f 2

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b856

Now that you have the SHA256 hash of the file to sign, you can create your signature request.

You need to provide at least the name of the signature request and the hash of the file to sign.
In this example, we additionally provide a list of authorized signers (with only 1 signer) and create the signature request in 'stateful' mode by setting its state to DRAFT (see Signature request life cycle for more details).

📘

Signers and signature modes

Depending on the signature mode you want to use for a signer, you have to provide specific information about it. For the most common signature by email mode, a common name and an email must be provided. For the signature face-to-face mode, a common name and a phone must be provided.
See the API reference documentation for more details.

Let's create your signature request using a simple curl command to do a POST request:

curl --request POST \
  -u <username>:<password> \
  --url https://api.woleet.io/v1/signatureRequest \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"name":"My signature request","hashToSign":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b856", "state":"DRAFT", "authorizedSignees":[{"commonName":"John Doe", "email":"[email protected]"}]}'

{
  "id":"d8cc4001-b6c4-414c-a721-0dc4b8764ce8",
  "created":1623660580688,
  "lastModified":1623660580688,
  "name":"My signature request",
  "state":"DRAFT",
  "hashToSign":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b856",
  "authorizedSignees":[
  	{
  		"auditTrailId":"95e89e6abd136f11e0a11c97f899024a3f8af7d17c15ef7e3b38b2c2f10467b1",
      "email":"[email protected]",
      "commonName":"John Doe"
    }
  ]
}

Your signature request is created! It can be modified as long as it is in DRAFT mode.

To start your signature request (ie. ask the platform to send signature invitation emails and start collecting signatures) you have to transition its state to 'PENDING'.

Let's do it by using a curl command to do a POST request:

curl --request POST \
  -u <username>:<password> \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '"PENDING"' \
  --url 'https://api.woleet.io/v1/signatureRequest/d8cc4001-b6c4-414c-a721-0dc4b8764ce8/transition'
  
 {
   "id":"d8cc4001-b6c4-414c-a721-0dc4b8764ce8",
   "created":1623660580688,
   "lastModified":1623663895111,
   "name":"My signature request",
   "state":"IN_PROGRESS",
   "hashToSign":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b856",
   "authorizedSignees":[{"auditTrailId":"95e89e6abd136f11e0a11c97f899024a3f8af7d17c15ef7e3b38b2c2f10467b1","email":"[email protected]","commonName":"John Doe"}]
 }

Because it has no activation date set, the platform automatically transitions your signature request to IN_PROGRESS and sends all required signature invitation emails to signers.

You are done!

You will receive a signature confirmation email after each signature, and the platform will eventually transition the signature request to COMPLETED and send you the signature attestation document by email when all signers have signed.

📘

Closing or canceling signature requests

You can decide to close a signature request before all signers have signed by transitioning it to CLOSED or to cancel it by transitioning it to CANCELED (in this case, the signature attestation document is NOT generated).

📘

Customizing the signature workflow

You have the possibility to widely customize the signature workflow:

• all types of emails sent during the workflow can be deactivated
• the templates of all types of emails can be overloaded
• the signature landing page can be fully customized by hosting your own version (possibly directly inside your business app).
• the logo and the colors of the signature attestation document can be modified

See Custom signature workflow for more details.

📘

What about Java, Javascript, Node, Python and PHP code samples?

For other programming languages, you can generate sample code using our actionable API Reference.