Signing flow

The signing flow

The signing flow represents the different steps a Signature will go through as detailed in the Signature Request's section.

In this page, we will focus on the two main stakeholders of the Signature Request: Approvers and Signers.

Approvers

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 attached to it, has given its approbation.

You can add up to 10 non-ordered approvers.

Once all the approvers approved the Signature Request the Signer(s) are notified.

Ordered and non-ordered Signers

When adding several Signers to the same Signature Request, you have the choice between two Signing flow depending on your specific use case.

Typeordered_signers
Non-ordered SignersfalseThis is the default behaviour.

If a Signature Request has several Signers they will all be requested to sign at the same time in no specific order.
Ordered SignerstrueEach Signer will be requested to sign one after the other: when Signer N signs, Signer N+1 will be able to sign. If Signer n does not sign, Signer n+1 will not be able to sign.

The order in which you added the Signers to the Signature Request will determine this signature order.

Ordered Signers example

Create an ordered Signature Request by setting ordered_signers property to true.

POST /signature_requests

{
    "name": "Signature Request with ordered signers",
    "delivery_mode": "email",
    "ordered_signers": true,
    "timezone": "Europe/Paris"
}

Upload your document as usual and then create the first Signer.

POST /signature_requests/{signatureRequestId}/signers

{
    "info": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone_number": "+33700000000",
        "locale": "fr"
    },
    "signature_level": "electronic_signature",
    "signature_authentication_mode": "no_otp",
    "fields": [
        {
            "document_id": "{{documentId}}",
            "type": "signature",
            "page": 1,
            "width": 180,
            "x": 400,
            "y": 650
        }
    ]
}
{
    "id": "d2c36369-76b5-4fe3-82f3-3987337d39ff",
    "info": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone_number": "+33700000000",
        "locale": "fr"
    },
    "status": "initiated",
    "signature_link": null,
    "signature_image_preview": "https://api.yousign.app/signature_requests/fa829dd9-e7e7-4c01-b5bd-fa207d77c69f/recipients/d2c36369-76b5-4fe3-82f3-3987337d39ff/preview.8c1e958b7a4b98845d6cc1cf81c45341c2312161.svg",
    "fields": [
        {
            "id": "279bd625-9f95-41b7-a840-901842397eac",
            "document_id": "cd38bbf8-4d1c-4d5b-bba8-3f1e8324e707",
            "type": "signature",
            "page": 1,
            "x": 400,
            "y": 650,
            "width": 180,
            "height": 37
        }
    ],
    "signature_level": "electronic_signature",
    "signature_authentication_mode": "no_otp",
    "redirect_urls": {
        "success": null,
        "error": null
    },
    "custom_text": {
        "request_subject": null,
        "request_body": null,
        "reminder_subject": null,
        "reminder_body": null
    }
}

To add a Signer that must sign after the Signer we just created, you have to retrieve the previous Signer ID (279bd625-9f95-41b7-a840-901842397eac) and use it in the `insert_after_id' property in Signer JSON payload:

{
    "insert_after_id": "279bd625-9f95-41b7-a840-901842397eac",
    "info": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone_number": "+33700000000",
        "locale": "fr"
    },
    "signature_level": "electronic_signature",
    "signature_authentication_mode": "no_otp",
    "fields": [
        {
            "document_id": "{{documentId}}",
            "type": "signature",
            "page": 1,
            "width": 180,
            "x": 400,
            "y": 650
        }
    ]
}

You can repeat this process if you need to add an another Signer.

📘

Ordered Workflow and Delivery Mode

If you use the delivery mode email (meaning that Yousign manages the email notification automatically for you), we will enforce the Ordered Signers workflow by sending the email respecting the ordering.

If you manage the delivery of the Signature Request (delivery_mode = "none"), you will have to enforce this order workflow.

You will send/show the link to the first Signer when you activate the Signature Request, but then you will need to wait for a confirmation of his signature to send/show the signature_link to the following Signer (for instance listening to the Webhooks "signer.notified").