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 enough signature and anchoring credits on your account to fulfill the signature request (each registered signature costs you 1 signature and 1 anchoring credit).

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 dedicated endpoint.

Available states:

DRAFT: the signature request is being edited (only DRAFT signature requests can be updated)
PENDING: the signature request is awaiting for its activation date
IN_PROGRESS: the activation date has been reached, 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
the auditTrialData and auditTrailAnchorId properties are set by the platform
the attestationAnchorId property is set by the platform (which implies that the Signature Attestation document and all the proof of signature receipts 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.

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 the documentation for more details.

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 (ie. the fingerprint) 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 not set or null, no activation date is applied.

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 to use to verify the signers' identity.

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

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 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 when 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 response body as a JSON object.

200The created signature request.