What is an Approver?

An Approver represents any person that needs to validate the content of a Signature Request before it can be signed. It can be, for example, a manager or a member of the legal service.

The use of Approvers allows you to build up a validation workflow for your Signature Requests. Indeed, a Signer will NOT be notified and therefore won't be able to sign a Signature Request until every Approver has given their approbation.

Add an Approver to a Signature Request

• Endpoint: Create a new Approver
• URL: POST /signature_requests/{signatureRequestId}/approvers
• Description: Adds an Approver to a given Signature Request.

An Approver can be any person implied in the validation process of a Signature Request. Therefore, it can be added in several ways:

• From scratch, by adding their first name, last name and email.
• As an existing User through its unique identifier.
• As an existing Contact through its unique identifier.
• As an existing Signer through its unique identifier. If a person is intended to approve and sign a Signature Request, it must be added as a Signer AND an Approver.

🚧

Limitations

• A maximum of 10 approvers can be added per Signature Request.

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

What if an Approver rejects a Signature Request?

If an Approver refuses to validate a Signature Request, it is possible for them to add a refusal reason. This value can be retrieved in the approver.rejected webhook event (see webhook payload).

Set Approvers ordering

When configuring a Signature Request, you can choose whether Approvers must complete their actions in a specific order or simultaneously.

This is controlled using the ordered_approvers parameter in the Signature Request creation endpoint.

Approval Modes:

Reorder Approvers

Approvers are ordered by default in the sequence they are created: the first created will be the first to approve. I.e. if you create Approver “A”, then Approver “B”, the Approvers ordering will be: A, B.

To change the default order, use the insert_after_id parameter available in the following endpoints:

• Create Approver
• Update Approver

Example: To insert Approver C after Approver A:

{
	"insert_after_id": "approver_A_id"
}

This sets the order: A → C → (others…)

Note: When insert_after_id is explicitly set to null, the approver will be moved to the top of the list."

Impact of Delivery Mode on Approver Flow

Each Approver can access and approve the Signature Request through a unique link. Depending on the delivery_mode configured for the Signature Request, this link will be sent to each one of them by email or returned in response to the Signature Request activation call. For more information about the Signature Request activation call, take a look at this page.

The enforcement of the sequential flow depends on the delivery mode:

Ordered Approvers and delivery mode

• Delivery mode Email:
  If you use the delivery mode email (meaning that Yousign manages the email notification automatically for you), Approvers are automatically notified in the correct sequence based on ordered_approvers = true.
• Delivery mode None
  If you use the delivery mode none (meaning that you are responsible for sharing the approval link), you will have to enforce this order flow.
  You must wait for each Approver’s status to update to notified before retrieving and sharing their approval link. Use the Webhook event: approver.notified to detect when to send the link.

Sequential Approval Flow Example

Signature Request with 3 Approvers: A, B, C

• Step 1: You activate the Signature Request:

  Approver	Approver status	approval_link
  A	notified	https://…
  B	initiated	null
  C	initiated	null

  • You share A’s link.
  • A approves.

• Step 2: B’s turn to approve

  	Approver status	approval_link
  A	approved	null
  B	notified	https://…
  C	initiated	null

  • You share B’s link.
  • B approves.

• Step 3: C’s turn to approve

  	Approver status	approval_link
  A	approved	null
  B	approved	null
  C	notified	https://…

  • You share C’s link.
  • C approves.