Signature request life cycle

The Woleet API supports stateful and stateless signature requests.

Stateless signature requests

📘

To create a stateless signature request, do not set its state property at creation time.

This type of request should be used when the full list of signers is unknown at request creation time and the requester therefore wishes to add signers on the fly. When the identity of a new signer is finally known, the requester appends it to the authorizedSignees property, and the platform sends the signature invitation email to the signer immediately (if applicable).

This type of request should also be used when anybody should be able to sign (ie. for a petition). In this mode, any valid signature is accepted, including pseudonymous signatures (ie. when no identity information is provided accept the signer's bitcoin address).

If a deadline is set and is reached, the platform automatically transitions the request to the EXPIRED state and freezes it, but not generate its audit trail. Thus, neither the request's proof bundle nor its signature attestation document can be downloaded.

The requester can close the request at any time by transitioning it to the CLOSED state. Doing this freezes the request and the platform generates and signs its audit trail, making the request's proof bundle and signature attestation document both downloadable.

The requester can cancel the request at any time by transitioning it to the CANCELED state. Doing this freezes the request, but the platform does not generate its audit trail. Thus, neither the request's proof bundle nor its signature attestation document can be downloaded.

Stateful signature requests

📘

To create a stateful signature request, set its state property to DRAFT at creation time.

This type of request should be used when the full list of signers is known at request creation time. Stateful signature requests can also manage an activation date.

A stateful signature request can only be modified while its state is DRAFT: once its state is IN_PROGRESS, no modification is allowed.

The requester starts the request by transitioning it to the PENDING state (note that if the request has an activation date, the requester can transition back the request to DRAFT until the activation date is reached).
When the activation date is reached (or immediately if none is set) the platform transitions the request to the IN_PROGRESS state and starts sending signature invitation emails to signers (if applicable) and collecting signatures.

Once all signers have signed, the platform transitions the request to the COMPLETED state.
If the expiration date is reached before all signers have signed, the platform transitions the request to the EXPIRED state.
The requester can close the request before all the signers have signed by transitioning it to the CLOSED state.
The requester can cancel the request before all the signers have signed by transitioning it to the CANCELED state.

When the request state is transitioned to CLOSED or COMPLETED, the request is frozen and the platform generates and signs its audit trail, making the request's proof bundle and signature attestation document both downloadable.

When the request state is transitioned to CANCELED or EXPIRED, the request is frozen but the platform does not generate its audit trail. Thus, neither the request's proof bundle nor its signature attestation document can be downloaded.