Create a new signature request.

post

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

Use this operation to create a new signature request.

The properties id, created and lastModified are read-only and so must not be provided: they are managed by the platform and added to the returned request.

Only the properties name and hashToSign are required: the hashToSign property must be the SHA256 hash of the file to sign.

Be sure to have at least 1 signature request credit, plus enough signature and SMS credits to fulfill the signature request.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

SignatureRequest object to create.

name

string

required

Name of the signature request (doesn't need to be unique).

state

string

enum

State of the signature request.

If not set, the signature request is stateless and can be updated at any time (eg. to add new signers on the fly).

If set to DRAFT at creation time, the signature request is stateful and its state can be transitioned using the /signatureRequest/{requestId}/transition endpoint.

Available states:

DRAFT: the signature request is being edited (only DRAFT signature requests can be updated)
PENDING: the signature request is waiting for its activation date to be reached
IN_PROGRESS: the signature request emails have been sent to the signers (if applicable) and the signatures are being collected
COMPLETED: all signatures have been collected
CLOSED: the signature request has been closed by the owner before all signatures could be collected
CANCELED: the signature request has been canceled by the owner before all signatures could be collected
EXPIRED: the deadline of the signature request has been reached before all signatures could be collected

Allowed:

callbackURL

string

Web hook to be called by the platform whenever:

the state property changes
a new signature is registered
the proofBundleComplete property is set to true by the platform (which means that the proof bundle and the Signature Attestation document are ready to download)

The platform does a POST request on this URL with the signature request as a JSON object in the request body. The domain of the URL must resolve to an external IP address.

Verifying the authenticity of the callback can be done by checking the HMAC-SHA1 signature of the request body provided by the platform in the x-woleet-signature header.

Please refer to this documentation for more details.

vars

object

The set of variables (key/value pairs) to use to customize the signature request workflow.

Values must be of type null, boolean, string or number: nested JSON objects are not allowed.

In particular, these variables can be used to customize the various email sent and disable some of these emails.

Please refer to this documentation for more details.

This property is only available to the owner and the signers of the signature request.

baseVarsKey

string

The key of an object in the user's k/v store to use as the base value of the vars property.

Properties defined in this object are overwritten by those defined in the vars property.

Use this property to store large customization variables shared by multiple signature requests (like email tempates).

lang

string

The preferred language (provided as an ISO 639-1 string) to use when emailing the signers.

public

boolean

true (or unset) if the signature request is public (ie. discoverable by its hashToSign) or false if it must be private (ie. not discoverable).

Signature anchors created in the scope of a signature request inherit from its public property.

hashToSign

string

required

SHA256 hash of the file to sign.

The value must be provided as an hexadecimal lowercase string. The hash of the empty file is forbidden.

activation

int64

Date of activation of the signature request (in milliseconds since Unix epoch).

When set, the platform waits for it before transitioning the signature request from PENDING to IN_PROGRESS automatically.

When not set, the platform transitions the signature request to IN_PROGRESS as soon as the signature request is transitioned to PENDING.

Only stateful signature request can have an activation date.

deadline

int64

Deadline of the signature request (in milliseconds since Unix epoch).

When not set or null, no deadline is applied.

If set, signatures registered after the deadline are refused.

identityURL

string

Web hook of the identity server to use to verify the signer's identity.

If set, it is used at signature registration time to verify the identity of the signers.

fileName

string

Name of the file to sign.

If set, the signature application can use it to give an indication about the file to the signers.

fileURL

string

Public URL of the file to sign.

If set, the signature application can use it to download and present the file to the signers.

maxSignatures

int32

Maximum number of signatures to accept for this signature request.

When not set or null, no maximum is applied.

This property and the authorizedSignees property are mutually exclusive.

This property is only available to the owner of the signature request.

authorizedSignees

array of objects

List of all signers authorized to register their signature (no duplicate is authorized).

When not set or null, anybody can sign the signature request.

If set, signers not being part of this list are not allowed to register their signature.

This property and the maxSignatures property are mutually exclusive.

authorizedSignees

watchers

array of objects

List of all watchers to notify by email about the progress of the signature request.

The set of events being notified are:

the signature request is activated
a signer signs the signature request
the signature request is canceled
the signature request is closed or completed and the Signature Attestation document is ready

This property is only available to the owner of the signature request.

watchers

ordered

boolean

true if the signers must sign in their order of appearance in the authorizedSignees list.

In this mode, each signer is notified only once the previous signer completes his signature.

Only stateful signature request can be ordered.

testMode

boolean

WARNING: Do not use (test purpose only).

Responses

400

Invalid request. More details are returned in the responsebody as a JSON object.

200The created signature request.