Each signer must be notified sequentially, when a signer signs then the next must be notified until there are no more signers to sign. To do this, the recommended way is by using webhooks.

📘

In delivery mode "email", the signer status "notified" implies that this signer has been notified by Yousign.

In delivery mode "none", the signer status "notified" implies that this signer is ready to be notified.

Find the next signer to notify from a webhook

When the delivery mode "none" is used, the signature link of the next ordered signer can be retrieved using webhooks.

1116 — Find the next signer's signature link for a Signature Request with delivery mode "none" with ordered signers

1. Create a webhook subscription

To detect when a signer needs to be notified, you have to create a webhook subscription listening to the event signer.notified (see Configure a new webhook).

2. Activate a Signature Request

When a signature request is created with a delivery_mode set to "none" and ordered_signers set to "true", the signature request activation (see Activate a signature request) will trigger the event signer.notified for the first ordered signer.

3. Receive the webhook payload

Once the signature request is created and activated, a request is sent to the webhook subscription that listens for the signer.notified event. This request contains the information of the first signer who needs to be notified.

Here is an example of the payload associated with this request:

{
  "event_id": "4d6305e0-a69a-4653-84e7-701c562b8f25",
  "event_name": "signer.notified",
  "event_time": "1669733581",
  "subscription_id": "d89a0f7b-bd3f-494d-ab61-71b69f24a3e1",
  "subscription_description": "App webhook",
  "sandbox": false,
  "data": {
    "signature_request": {
      "id": "b9bf5521-00eb-4044-adf5-da4ea31a48e0",
      "status": "ongoing",
      "name": "My new request",
      "delivery_mode": "none",
      "created_at": "2022-11-29T14:52:39+00:00",
      "timezone": "Europe/Paris",
      "email_custom_note": null,
      "expiration_date": "2023-05-29T21:59:00+00:00",
      "source": "app",
      "ordered_signers": true,
      "external_id": null,
      "signers": [
        {
          "id": "395375bb-93d9-4762-8e11-5caa4734afc1",
          "answers": [],
          "status": "notified"
        }
      ],
      "approvers": [],
      "sender": {
        "id": "3409ab3f-9295-4a69-9923-e9d32d9533d6",
        "email": "[email protected]"
      },
      "documents": [
        {
          "id": "5dcae863-2a1b-4f93-92a7-73f6b7409474",
          "nature": "signable_document"
        }
      ],
      "reminder_settings": {
        "interval_in_days": 7,
        "max_occurrences": 5
      }
    },
    "signer": {
      "id": "395375bb-93d9-4762-8e11-5caa4734afc1",
      "info": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone_number":"+33700000000",
        "locale": "en"
      },
      "answers": [],
      "status": "notified",
      "signature_level": "electronic_signature",
      "signature_authentication_mode": "sms"
    }
  }
}

4. Fetch the Signer's signature link

The signer ID can be found in the payload (here it's 395375bb-93d9-4762-8e11-5caa4734afc1), and the signature link can be retrieved by requesting the API. In this example, the request would be as follows:

GET /signature_requests/b9bf5521-00eb-4044-adf5-da4ea31a48e0/signers/395375bb-93d9-4762-8e11-5caa4734afc1

{
    "id": "395375bb-93d9-4762-8e11-5caa4734afc1",
    "info": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone_number": "+33700000000",
        "locale": "en"
    },
    "status": "notified",
    "signature_link": "https://yousign.app/signatures/70852b46-d0b1-4901-8178-9aefafae6cf6?s=d364cf2b709f33cc54ad2de28c61fb556bfa9b50d8fca088866d28afafd8e6c1472ebd5e5cbd4f0edf7ddf04525d70142b32d1d181d1ea97e45c863d92311dcb&r=7dcae4cc66676747516cce62a4af3404&source=email&lang=fr&magic_link_id=305b933d-899a-4d3b-b4c0-13bc859ec82b&domain_id=1b242e08f4&k=gaWNhPwxgARPJ7sDGGT9zms47HueiSz5",
    "signature_link_expiration_date": "2023-05-05T09:28:57+00:00",
    "signature_image_preview": "https://yousign.app/signature_requests/70852b46-d0b1-4901-8178-9aefafae6cf6/recipients/c591d3c1-bc02-4cbd-a941-206aa7c6a406/preview.8c1e958b7a4b98845d6cc1cf81c45341c2312161.svg",
    "fields": [
        {
            "id": "6364a7c2-34b6-4bbe-bb60-d07724400a67",
            "document_id": "22b93593-8631-45e9-b4ac-2a3a820d6034",
            "x": 56,
            "y": 231,
            "page": 1,
            "type": "signature",
            "height": 100,
            "width": 200
        },
        {
            "id": "fc5b59a5-4cc0-4e3b-a959-7ec7f3aada27",
            "document_id": "22b93593-8631-45e9-b4ac-2a3a820d6034",
            "x": 56,
            "y": 343,
            "page": 1,
            "type": "signature",
            "height": 102,
            "width": 101
        }
    ],
    "signature_level": "electronic_signature",
    "signature_authentication_mode": "otp_sms",
    "redirect_urls": {
        "success": null,
        "error": null
    },
    "custom_text": {
        "request_subject": null,
        "request_body": null,
        "reminder_subject": null,
        "reminder_body": null
    }
}

5. Notify the signer

You can now use the signature_link value to send an invitation to sign to this signer.

📘
Repeat the process until no signer is left to sign.