Signature Request

The Signature Request is the key concept that you are going to manipulate to sign your documents. It represents the process of inviting signers to sign a document. It exists different statuses for these signature requests according to their state of completion. You can choose how to notify the stakeholders of this signature request.

All the endpoints available to manage Signature Requests can be found in our API Reference.

Here are the different Signature Request's status

Status summary

StatusDetails
DraftThe signature has not been activated yet.
ApprovalThe Signature Request has been activated and needs to be approved by one or many approvers.
RejectedAt least one approver rejected the Signature Request
OngoingThe Signature Request has been activated and the approvers, if any, approved it.
DeclinedA signer has declined the Signature Request.
ExpiredThe Signature Request expiration date has passed. An expired Signature Request can be reactivated. The default validity period is 6 months from the activation.
DeletedThe Signature Request has been deleted. All Signature Requests can be deleted except those with an “Approval” and “Ongoing” status. A deleted Signature Request can be reactivated from the application.
CanceledThe Signature Request has been cancelled. A cancelled Signature Request can't be reactivated. A Signature Request needs to have the "Approval" or "Ongoing" status to be cancelled.
DoneThe Signature Request is done. All approvers approved and all Signers signed the document.

Signature flow

Signature Request Delivery Mode

The delivery mode allows you to choose how the signature request's Signers and Approvers will be notified.

Two delivery modes exist:

  • Email: Yousign is in charge of delivering all the notifications to the Signature Request stakeholders. This is the recommended delivery mode if you don't want to implement by yourself all the notifications to the stakeholders.
  • None: you are in charge of delivering the different notifications to the Signature Request stakeholders. This delivery mode is for advanced use cases only and is only available for simple Signature Requests.
    More details about this delivery mode can be found here. If you update the email address of a signer or an approver after the Signature Request activation, all previously sent signature links are disabled. You will have to fetch the new signature links and send them again to the Signature Request participants.

Signature Request workspace

Workspaces allow you to ensure the confidentiality of documents between your users or reflect the organization of your company (departments, subsidiaries, agencies...).

When you create a Signature Request you can choose to store it in a specific Workspace. Otherwise, the Signature Request will be stored in the oldest active Workspace.

If you create a Signature Request from a Template, if it scoped to Organization (not in a specific Workspace), you can choose the Workspace in which the SR will be stored. Otherwise, the Signature Request will be stored in the oldest active Workspace.
But if the Template is in a specific Workspace, if you pass a workspace in payload; this must be identical to the Workspace linked to the Template.
If you do not provide this information, the Signature Request will be automatically stored in the same Workspace as the Template.

More details about Workspaces can be found here and about Templates can be found here.

Signature Request Sender Name customisation

If the delivery mode is set to email, then Signature Requests notifications are sent by Yousign on your behalf.

By default, the sender's name will be the name of your Organisation. However, you can choose to personalise the Signature Request Sender Name.

This Signature Request Sender Name is used:

  • In the email sender, subject and signature.
  • In the text displayed in the Signing Flow.

To personalise the sender's name, you have to use the email_notificationfield in the /POST Signature Request endpoint.

3 options are available :

The sender's name is the Organisation's name.

This is the default behaviour, but if you want to make it explicit, you just have to add this payload in your /POST Signature Request

"email_notification": {  
    "sender": {  
      "type": "organization"  
    }  
  }

The logo displayed in the notification emails and the Signing Flow will be the one from the Organisation or the one from the Custom Experience if set.

The sender's name is the Workspace's name.

Every Signature Request is associated with a specific Workspace as described here. By selecting this option, the sender's name will have the Workspace's name in which the Signature Request is created. This Workspace's name can be changed directly from your Yousign account. Here is what you need to add to your /POST Signature Requestpayload.

"email_notification": {  
    "sender": {  
      "type": "workspace"  
    }  
  }

The logo displayed in the notification emails and the Signing Flow will be a default logo chosen by Yousign or the one from the Custom Experience if set.

The sender's name is a custom value

You can personalise the Signature sender's name with a custom value. Here is what you need to add to your /POST Signature Requestpayload.

"email_notification": {  
    "sender": {  
      "type": "custom",
      "custom_name": "A very custom name"
    }  
  }

A logo will be displayed in the notification emails and the Signing Flow only if set in the associated Custom Experience

Signature Request deletion

The delete endpoint offers two distinct deletion options based on the value of the parameter permanent_delete:

  • Delete a Signature Request (set by default)

  • Permanently delete a Signature Request

Rules

  • This endpoint supports Signature Requests in any status except approval and ongoing.
  • For Signature Requests in approval or ongoing status, they must first be moved to another status before being permanently deleted.

Delete a Signature Request

When the permanent_delete parameter is set to false, the signature is sent to the trash. Once deleted this way, the Signature Request status becomes deleted .

Behavior:

  • Deleted Signature Request are accessible on the application on the trash list.
  • Deleted Signature Requests can be restored from the trash list within the application.

Permanently Delete a Signature Request

When the permanent_delete parameter is set to true, it triggers the permanent deletion of the signature request.

Behavior:

  • The Signature Request is permanently deleted and cannot be restored.
  • The permanent deletion can also be used on a deleted Signature Request.

Webhook
The permanent deletion of a Signature Request is carried out asynchronously. The webhook signature_request.permanently_deleted is available to notify you when the deletion process is complete. This permanent deletion will take effect after a few seconds.